state-machines

name	state-machines
description	State machines with XState — modeling complex UI flows, form wizards, async processes, and actor-based architecture
layer	domain
category	state-management
triggers	["state machine","xstate","finite state","statechart","state transition","actor model","complex flow"]
inputs	["flow requirements","states","transitions","side effects"]
outputs	["state machine definitions","React integration","visualizations","tests"]
linksTo	["state-management","react","forms","typescript-patterns"]
linkedFrom	["ui-ux-pro","testing-patterns"]
preferredNextSkills	["state-management","testing-patterns"]
fallbackSkills	["react"]
riskLevel	low
memoryReadPolicy	selective
memoryWritePolicy	none
sideEffects	[]

State Machines with XState

Purpose

State machines make complex, stateful UI flows explicit and predictable. Instead of scattered boolean flags and useEffect chains, you define all possible states, transitions, and side effects in a single, testable machine. XState (v5) is the standard implementation for JavaScript/TypeScript.

When to Use

• Multi-step forms / wizards
• Authentication flows (idle > loading > authenticated > error)
• Payment / checkout processes
• Media players (play, pause, buffer, error)
• Complex modals with conditional steps
• Any flow with more than 3 states or conditional transitions

XState v5 Basics

Defining a Machine

import { setup, assign, fromPromise } from 'xstate';

interface AuthContext {
  user: User | null;
  error: string | null;
  retries: number;
}

type AuthEvent =
  | { type: 'LOGIN'; email: string; password: string }
  | { type: 'LOGOUT' }
  | { type: 'RETRY' };

const authMachine = setup({
  types: {
    context: {} as AuthContext,
    events: {} as AuthEvent,
  },
  actors: {
    loginUser: fromPromise(async ({ input }: { : { : ; :  } }) => {
       response =  (, {
        : ,
        : { :  },
        : .(input),
      });
       (!response.)   ();
       response.()  <>;
    }),
  },
  : {
    :  context. < ,
  },
}).({
  : ,
  : ,
  : { : , : , :  },
  : {
    : {
      : {
        : { :  },
      },
    },
    : {
      : {
        : ,
        :  ({
          : (event  { : ; : ; :  }).,
          : (event  { : ; : ; :  }).,
        }),
        : {
          : ,
          : ({ :  event., :  }),
        },
        : {
          : ,
          : ({
            :  (event.  ).,
            :  context. + ,
          }),
        },
      },
    },
    : {
      : { : { : , : ({ :  }) } },
    },
    : {
      : {
        : { : , :  },
        : { :  },
      },
    },
  },
});