0
# @xstate/react
1

2
@xstate/react provides React-specific utilities and hooks for integrating XState finite state machines and statecharts into React applications. It offers comprehensive state management capabilities with automatic re-rendering, TypeScript integration, and SSR compatibility.
3

4
## Package Information
5

6
- **Package Name**: @xstate/react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install xstate @xstate/react`
10

11
Note: XState is a peer dependency and must be installed separately.
12

13
## Core Imports
14

15
```typescript
16
import { useActor, useActorRef, useSelector, createActorContext, shallowEqual } from "@xstate/react";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { useActor, useActorRef, useSelector, createActorContext, shallowEqual } = require("@xstate/react");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { useActor } from "@xstate/react";
29
import { createMachine } from "xstate";
30

31
const toggleMachine = createMachine({
32
  id: "toggle",
33
  initial: "inactive",
34
  states: {
35
    inactive: { on: { TOGGLE: "active" } },
36
    active: { on: { TOGGLE: "inactive" } }
37
  }
38
});
39

40
function Toggle() {
41
  const [state, send] = useActor(toggleMachine);
42

43
  return (
44
    <button onClick={() => send({ type: "TOGGLE" })}>
45
      {state.value === "inactive" ? "Click to activate" : "Active! Click to deactivate"}
46
    </button>
47
  );
48
}
49
```
50

51
## Architecture
52

53
@xstate/react is built around several key components:
54

55
- **React Hooks**: Core hooks (`useActor`, `useActorRef`, `useSelector`) that manage XState actors within React's lifecycle
56
- **Context System**: `createActorContext` for sharing actors across component trees via React Context
57
- **State Synchronization**: Integration with React's `useSyncExternalStore` for optimal re-rendering
58
- **SSR Compatibility**: Isomorphic layout effects for server-side rendering support
59
- **Type Safety**: Full TypeScript integration preserving XState's type system in React components
60

61
## Capabilities
62

63
### Core State Management Hooks
64

65
Primary hooks for managing XState actors and subscribing to state changes with automatic React integration.
66

67
```typescript { .api }
68
function useActor<TLogic extends AnyActorLogic>(
69
  logic: TLogic,
70
  options?: ActorOptions<TLogic>
71
): [SnapshotFrom<TLogic>, Actor<TLogic>['send'], Actor<TLogic>];
72

73
function useActorRef<TLogic extends AnyActorLogic>(
74
  machine: TLogic,
75
  options?: ActorOptions<TLogic>,
76
  observerOrListener?: Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void)
77
): Actor<TLogic>;
78

79
function useSelector<TActor, T>(
80
  actor: TActor,
81
  selector: (snapshot: TActor extends { getSnapshot(): infer TSnapshot } ? TSnapshot : undefined) => T,
82
  compare?: (a: T, b: T) => boolean
83
): T;
84
```
85

86
[Core Hooks](./core-hooks.md)
87

88
### Context and Provider Utilities
89

90
Factory function for creating React context providers and hooks for sharing XState actors across component trees.
91

92
```typescript { .api }
93
interface ActorContextReturn<TLogic extends AnyActorLogic> {
94
  useSelector: <T>(
95
    selector: (snapshot: SnapshotFrom<TLogic>) => T,
96
    compare?: (a: T, b: T) => boolean
97
  ) => T;
98
  useActorRef: () => Actor<TLogic>;
99
  Provider: React.ComponentType<{
100
    children: React.ReactNode;
101
    options?: ActorOptions<TLogic>;
102
    logic?: TLogic;
103
  }>;
104
}
105

106
function createActorContext<TLogic extends AnyActorLogic>(
107
  actorLogic: TLogic,
108
  actorOptions?: ActorOptions<TLogic>
109
): ActorContextReturn<TLogic>;
110
```
111

112
[Context Utilities](./context-utilities.md)
113

114
### Utility Functions
115

116
Helper functions for common operations and compatibility.
117

118
```typescript { .api }
119
function shallowEqual(objA: any, objB: any): boolean;
120

121
// Deprecated - use useActor instead
122
function useMachine<TMachine extends AnyStateMachine>(
123
  machine: TMachine,
124
  options?: ActorOptions<TMachine>
125
): [StateFrom<TMachine>, Actor<TMachine>['send'], Actor<TMachine>];
126
```
127

128
[Utility Functions](./utility-functions.md)
129

130
## Common Types
131

132
The following types are commonly used throughout the @xstate/react API:
133

134
```typescript { .api }
135
// From XState - these types are re-exported or used in signatures
136
type AnyActorLogic = any; // XState's actor logic type
137
type Actor<TLogic> = any; // XState's actor reference type
138
type SnapshotFrom<TLogic> = any; // Extracted snapshot type from logic
139
type ActorOptions<TLogic> = any; // XState's actor configuration options
140
type Observer<T> = any; // XState's observer interface
141
type AnyStateMachine = any; // XState's state machine type
142
type StateFrom<TMachine> = any; // Extracted state type from machine
143

144
// React integration types
145
interface ReactNode {} // React's node type for children
146
interface ComponentType<P> {} // React's component type
147
```
148

149
Note: These types are defined by XState and React. Refer to their respective documentation for complete type definitions.