react-state-machine

name	react-state-machine
description	Building reusable React state machine skills with XState v5 and the actor model
user-invocable	false
disable-model-invocation	true
version	1.0.1
category	development
author	Claude MPM Team
license	MIT
progressive_disclosure	{"entry_point":{"summary":"Build type-safe, visualizable React state machines using XState v5's actor model for predictable UI behavior","when_to_use":"Complex async flows, multi-step forms, modal animations, media players, boolean flag explosion, defensive coding patterns","quick_start":"1. Define states/events with setup() 2. Use promise actors for async 3. useMachine for simple, useActorRef+useSelector for performance 4. Test with createActor 5. Visualize in Stately Studio"},"references":["xstate-v5-patterns.md","react-integration.md","skills-architecture.md","testing-patterns.md","decision-trees.md","real-world-patterns.md","error-handling.md","performance.md","persistence-hydration.md","migration-guide.md","composition-patterns.md"]}
context_limit	700
tags	["react","state-machine","xstate","actors","async","forms","ui-logic"]
requires_tools	[]

React State Machines with XState v5

Overview

State machines make impossible states unrepresentable by modeling UI behavior as explicit states, transitions, and events. XState v5 (2.5M+ weekly npm downloads) unifies state machines with the actor model—every machine is an independent entity with its own lifecycle, enabling sophisticated composition patterns.

When to Use This Skill

Trigger patterns:

• Boolean flag explosion: multiple isLoading, isError, isSuccess flags
• Implicit states: writing if (isLoading && !isError && data) to derive mode
• Defensive coding: guards before state updates to prevent invalid transitions
• Timing coordination: timeouts, delays, debouncing across states
• State dependencies: one state depends on another to update correctly

Do not use for:

• Simple boolean toggles with no async (useState is simpler)
• Single form fields with basic validation (useReducer suffices)
• Server state caching (React Query/TanStack Query handles this)
• Static data transformations (useMemo is better)
• Simple counters or toggles (useState is clearer)

See decision-trees.md for comprehensive decision guidance

Core Mental Model

Finite states represent modes of behavior: idle, loading, success, error. A component can only be in ONE state at a time.

Context (extended state) stores quantitative data that doesn't define distinct states. The finite state says "playing"; context says what at what volume.

Events trigger transitions between states. Events are objects: { type: 'SUBMIT', data: formData }.

Guards conditionally allow/block transitions: { guard: 'hasValidInput' }.

Actions are fire-and-forget side effects during transitions or state entry/exit.

Invoked actors are long-running processes (API calls, subscriptions) with lifecycle management and cleanup.

Quick Start: XState v5 setup() Pattern

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

 fetchMachine = ({
  : {
    : {}  { :  | ; :  |  },
    : {}  
      | { : ; :  }
      | { :  }
  },
  : {
    : ( ({ input, signal }) => {
       res =  (, { signal });
       (!res.)   (res.);
       res.();
    })
  },
  : {
    : ({ :  event. }),
    : ({ :  event.. })
  }
}).({
  : ,
  : ,
  : { : , :  },
  : {
    : { : { :  } },
    : {
      : {
        : ,
        :  ({ : event. }),
        : { : , :  },
        : { : , :  }
      }
    },
    : { : { :  } },
    : { : { :  } }
  }
});