XState in React: State Machines for Complex UI States

1. Why state machines for complex UI states

A checkout process with a cart, address, payment and confirmation step does not just have one loading boolean in practice, it has dozens of possible combinations of loading state, error state and validation status. Modeling that with several independent useState booleans almost inevitably creates impossible combinations of state, for example isLoading and isError both true at once, even though that should never happen from a business perspective. XState solves this by modeling UI logic as a finite automaton: exactly one active state exists at any point in time, and only explicitly defined transitions between states are possible.

The theoretical foundation of XState is statecharts, an extension of finite automata formalized by David Harel in the 1980s that adds hierarchy, parallelism and history states. XState translates this model almost completely into a JavaScript and TypeScript API, allowing complex UI logic to be expressed in a form that is both machine executable and visually understandable for humans. For React applications, that means state machines take over exactly the cases where useReducer reaches its limits, because too many implicit combinations of state become possible.

The appeal of state machines does not lie in added complexity, quite the opposite: explicitly modeled states and transitions make impossible states impossible, instead of avoiding them by convention. This property makes state machines particularly valuable for forms, wizard flows, media players and anything that manages more than two or three independent boolean flags at once.

2. Core concepts: states, events, transitions and context

A state machine in XState consists of a fixed set of named states, for example idle, loading, success and error. Events are the only trigger for switching between states, for example FETCH, RESOLVE or REJECT. A transition defines which state follows which event in which source state, and exactly this explicit mapping prevents an event from accidentally triggering something unexpected in an inappropriate state.

Besides the discrete states, XState manages context, an arbitrary JavaScript object for data that does not itself determine the state but gets updated during transitions, for example loaded data or an error message. This separation between state, which describes the structure of the flow, and context, which holds the concrete data, is the core of the XState model and differs fundamentally from a single reducer that mixes state and data into one object.

// machines/fetchMachine.ts — a finite state machine models exactly the reachable states
import { setup, assign } from 'xstate';

export const fetchMachine = setup({
  types: {} as {
    context: { data: unknown; error: string | null };
    events: { type: 'FETCH' } | { type: 'RESOLVE'; data: unknown } | { type: 'REJECT'; error: string };
  },
}).createMachine({
  id: 'fetch',
  initial: 'idle',
  context: { data: null, error: null },
  states: {
    idle: { on: { FETCH: 'loading' } },
    loading: {
      on: {
        RESOLVE: { target: 'success', actions: assign({ data: ({ event }) => event.data }) },
        REJECT: { target: 'error', actions: assign({ error: ({ event }) => event.error }) },
      },
    },
    success: { on: { FETCH: 'loading' } },
    error: { on: { FETCH: 'loading' } },
  },
});

3. Integrating XState in React with useMachine

The useMachine hook from the @xstate/react package connects an XState machine to the React lifecycle: on the first render the machine is interpreted and started, and on every state change the hook triggers a rerender of the component with the current snapshot. The returned state contains both the current state name via state.matches('loading') and the current context via state.context, while send dispatches events to the machine.

An important benefit of this integration: because all transition logic lives in the machine definition rather than in the component, the same machine can be reused without friction in Storybook, in unit tests, or even in a different environment such as Node.js without React. The component itself becomes a pure presentation layer that reacts to state.matches(...) checks, without containing its own state logic.

// components/DataFetcher.jsx — useMachine connects the machine to the React render cycle
import { useMachine } from '@xstate/react';
import { fetchMachine } from '../machines/fetchMachine';

function DataFetcher() {
  const [state, send] = useMachine(fetchMachine);

  return (
    <div>
      {state.matches('idle') && <button onClick={() => send({ type: 'FETCH' })}>Load</button>}
      {state.matches('loading') && <p>Loading…</p>}
      {state.matches('success') && <pre>{JSON.stringify(state.context.data)}</pre>}
      {state.matches('error') && <p role="alert">{state.context.error}</p>}
    </div>
  );
}

4. Guards and actions: conditional transitions and side effects

Guards are condition functions that only allow a transition to happen if they return true, for example to advance a wizard step only if the validation of the current form section succeeded. Unlike a scattered if condition in an event handler, a guard is declared directly on the transition itself and is therefore immediately visible in the context of the affected transition, without having to search for the logic elsewhere.

Actions are side effects executed on a transition, for example updating context via assign, sending an analytics event, or calling an external callback function. Because actions are explicitly bound to states or transitions, the machine definition alone reveals when which side effect happens, without having to search through the entire component code.

// machines/wizardMachine.ts — guards gate transitions, actions run as side effects
import { setup, assign } from 'xstate';

export const wizardMachine = setup({
  types: {} as { context: { email: string }; events: { type: 'NEXT' } },
  guards: {
    isEmailValid: ({ context }) => /\S+@\S+\.\S+/.test(context.email),
  },
  actions: {
    trackStepCompleted: () => console.log('analytics: step completed'),
  },
}).createMachine({
  id: 'wizard',
  initial: 'contactInfo',
  context: { email: '' },
  states: {
    contactInfo: {
      on: {
        NEXT: {
          target: 'shipping',
          guard: 'isEmailValid', // transition is blocked unless this returns true
          actions: 'trackStepCompleted',
        },
      },
    },
    shipping: { type: 'final' },
  },
});

5. Hierarchical and parallel states

Real UI flows rarely consist of a flat list of states. A media player has a parent state playing, which in turn can contain sub states such as buffering or normal, while independently at the same time having a parallel state for volume control. XState supports hierarchical states (also called compound states), where a state itself contains a complete, nested state machine, as well as parallel states, where several independent regions are active at the same time.

This nesting prevents a combinatorial explosion of flat states: instead of defining playingBuffering, playingNormal, pausedBuffering and so on as separate flat states, the buffering information is modeled as a sub state of playing, which drastically reduces the number of transitions to maintain and keeps the machine definition closer to the actual structure of the problem.

// machines/playerMachine.ts — hierarchical (nested) and parallel states
import { setup } from 'xstate';

export const playerMachine = setup({ types: {} }).createMachine({
  id: 'player',
  type: 'parallel',
  states: {
    playback: {
      initial: 'paused',
      states: {
        paused: { on: { PLAY: 'playing' } },
        playing: {
          initial: 'normal',
          on: { PAUSE: 'paused' },
          states: {
            normal: { on: { BUFFER: 'buffering' } },
            buffering: { on: { BUFFERED: 'normal' } },
          },
        },
      },
    },
    volume: {
      initial: 'unmuted',
      states: {
        unmuted: { on: { MUTE: 'muted' } },
        muted: { on: { UNMUTE: 'unmuted' } },
      },
    },
  },
});

6. The actor model: letting multiple machines communicate

Starting with XState version 5, the actor model is the central abstraction: every state machine, every promise based actor, and even simple callback functions are actors, started via invoke or spawn from a parent machine and communicating with each other through events. A form wizard can spawn its own independent actor for every step, each managing its own state, without the parent machine having to know that actor's internal state.

This model scales considerably better than a single monolithic machine for the whole application: every actor encapsulates its own responsibility, communicates outward only through explicitly defined events, and can be tested independently of the other actors. For complex applications with many parallel but loosely coupled processes, for example several files uploading at once with their own progress each, the actor model is the natural approach.

7. Testing state machines: model based testing

A decisive practical advantage of XState lies in testing: because a machine definition is a complete, declarative description of all possible states and transitions, it can be tested entirely independently of React, without Testing Library or DOM rendering. A simple unit test calls fetchMachine.transition(state, event) and checks whether the resulting state and context match expectations, with no rendered component at all.

For more thorough coverage, @xstate/test offers model based testing: all reachable paths through the state graph are generated automatically from the machine definition, and a test scenario is run for each path. This covers combinations of state transitions that hand written tests frequently miss, because no one manually thinks through every possible order of events.

8. Visualization with Stately Studio

An often underestimated benefit of XState is visual representation: since a machine definition is a plain JavaScript or JSON object, it can be rendered automatically as a diagram. Stately Studio, the official tool from the XState team, visualizes states, transitions and the currently active state live during development, letting product managers and non technical stakeholders read the UI logic without touching code.

In practice, Stately Studio is often used to discuss complex flows together with business departments before any code is written at all: a diagram with boxes and arrows communicates a checkout flow far more clearly than a list of useState calls. Changes to the machine definition are immediately reflected in the diagram, which permanently keeps documentation and actual code behavior in sync, without needing to maintain a separate architecture document.

9. XState compared to useReducer and useState

XState is not a replacement for useState or useReducer in every situation, but a targeted escalation step for cases with genuine state complexity. The table below shows when which approach is appropriate.

10. Summary

XState models complex UI logic as a finite automaton with explicit states, events and transitions, which structurally rules out impossible combinations of state instead of relying on convention. Guards control conditional transitions, actions encapsulate side effects, and hierarchical as well as parallel states prevent a combinatorial explosion of flat state definitions. The actor model introduced in version 5 scales this approach to complex applications with many independent but communicating processes.

For simple, independent values, useState and useReducer remain the right choice, XState only pays off once there is genuine state complexity such as wizards, checkout processes or media players. The extra investment in statecharts pays off long term through model based testing and automatic visualization via Stately Studio, because entire classes of bugs caused by impossible combinations of state are ruled out from the start.

11. FAQ: XState and State Machines