XState React Integration

XState React Integration

Connect XState machines to React components with useMachine, useActor, and useSelector hooks

When to Use

• Rendering UI based on the current state of a machine
• Sending events to a machine from React event handlers
• Sharing a machine instance across multiple components via context
• Reading machine context and matching states for conditional rendering

Instructions

1. Use useMachine(machine) to create and interpret a machine instance local to a component.
2. Destructure [state, send, actorRef] from the hook. state contains the current state; send dispatches events.
3. Use state.matches('stateName') for conditional rendering — never compare state.value as a string directly (it can be an object for compound states).
4. Access machine context via state.context.
5. For shared machines across components, create the actor with useActorRef in a parent and pass it down via React context. Children use useSelector to read specific state slices.
6. Use useSelector with a comparison function to prevent unnecessary re-renders.

// LoginForm.tsx
import { useMachine } from '@xstate/react';
import { authMachine } from './auth.machine';

function LoginForm() {
  const [state, send] = useMachine(authMachine, {
    // Provide service implementations
    services: {
      authenticateUser: async (ctx, event) => {
        const res = await fetch('/api/login', {
          method: 'POST',
          body: JSON.stringify({ email: event.email, password: event.password }),
        });
        if (!res.ok) throw new Error('Invalid credentials');
        return res.json();
      },
    },
  });

  if (state.matches('authenticated')) {
    return <div>Welcome, {state.context.user?.name}</div>;
  }

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const data = new FormData(e.currentTarget);
        send({ type: 'LOGIN', email: data.get('email') as string, password: data.get('password') as string });
      }}
    >
      <input name="email" type="email" />
      <input name="password" type="password" />
      <button disabled={state.matches('authenticating')}>
        {state.matches('authenticating') ? 'Signing in...' : 'Sign in'}
      </button>
      {state.matches('error') && <p>{state.context.error}</p>}
    </form>
  );
}

// Shared machine via React context
import { createActorContext } from '@xstate/react';
import { appMachine } from './app.machine';

const AppMachineContext = createActorContext(appMachine);

function App() {
  return (
    <AppMachineContext.Provider>
      <Header />
      <Content />
    </AppMachineContext.Provider>
  );
}

function Header() {
  const userName = AppMachineContext.useSelector(
    (state) => state.context.user?.name
  );
  return <header>{userName ?? 'Guest'}</header>;
}

Details

useMachine vs useActorRef: useMachine creates a new actor on mount and re-renders the component on every state change. useActorRef creates the actor but does NOT cause re-renders — combine with useSelector for surgical updates.

state.matches deep matching: For compound states, state.matches('playing.fastForward') checks nested states. For parallel states, pass an object: state.matches({ bold: 'on', italic: 'off' }).

useSelector for performance: Instead of re-rendering on every state change, select only what you need:

const isLoading = AppMachineContext.useSelector((state) => state.matches('loading'));
// Component only re-renders when isLoading changes

XState v5 with @xstate/react v4:

import { useMachine, useActorRef, useSelector } from '@xstate/react';

// useMachine still works the same
const [snapshot, send] = useMachine(machine);

// snapshot.value, snapshot.context, snapshot.matches() work identically

Testing components with machines: Pass a pre-configured machine or use @xstate/react/lib/test utilities. Override services to return mock data.

Common mistakes:

• Creating a new machine reference on every render (define machines outside components)
• Using state.value === 'loading' instead of state.matches('loading') — breaks for compound states
• Not providing required services to useMachine — the machine runs but invocations fail silently

Source

https://stately.ai/docs/xstate-react

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.