xstate

name	xstate
description	XState v5 state machines and statecharts for JavaScript/TypeScript
context	fork
allowed-tools	Read, Bash, Glob, Grep

XState v5

Actor-based state management & orchestration for complex app logic.

Repository: statelyai/xstate Language: TypeScript Stars: 29,364 License: MIT License

⚡ Quick Reference

Basic State Machine

import { createMachine, createActor, assign } from 'xstate';

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  context: { count: 0 },
  states: {
    inactive: {
      on: { TOGGLE: { target: 'active' } }
    },
    active: {
      entry: assign({ count: ({ context }) => context.count + 1 }),
      on: { TOGGLE: { target: 'inactive' } }
    }
  }
});

const actor = createActor(toggleMachine);
actor.subscribe((state) => console.log(state.value, state.context));
actor.start();
actor.send({ type: 'TOGGLE' });

Setup API with Type Safety

import { setup, assign } from 'xstate';

const machine = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: 'INCREMENT' } | { type: 'DECREMENT' }
  },
  actions: {
    increment: assign({ count: ({ context }) => context.count + 1 }),
    decrement: assign({ count: ({ context }) => context.count - 1 })
  }
}).createMachine({
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      on: {
        INCREMENT: { actions: 'increment' },
        DECREMENT: { actions: 'decrement' }
      }
    }
  }
});

Hierarchical States

const lightMachine = createMachine({
  id: 'light',
  initial: 'green',
  states: {
    green: { on: { TIMER: 'yellow' } },
    yellow: { on: { TIMER: 'red' } },
    red: {
      on: { TIMER: 'green' },
      initial: 'walk',
      states: {
        walk: { on: { PED_TIMER: 'wait' } },
        wait: { on: { PED_TIMER: 'stop' } },
        stop: {}
      }
    }
  }
});

Parallel States

const wordMachine = createMachine({
  id: 'word',
  type: 'parallel',
  states: {
    bold: {
      initial: 'off',
      states: {
        on: { on: { TOGGLE_BOLD: 'off' } },
        off: { on: { TOGGLE_BOLD: 'on' } }
      }
    },
    italics: {
      initial: 'off',
      states: {
        on: { on: { TOGGLE_ITALICS: 'off' } },
        off: { on: { TOGGLE_ITALICS: 'on' } }
      }
    }
  }
});

React Integration

import { useActor } from '@xstate/react';

function ToggleComponent() {
  const [state, send] = useActor(toggleMachine);

  return (
    <div>
      <p>State: {state.value}</p>
      <p>Count: {state.context.count}</p>
      <button onClick={() => send({ type: 'TOGGLE' })}>
        Toggle
      </button>
    </div>
  );
}

XState Store (Simple State Management)

import { createStore } from '@xstate/store';

const store = createStore({
  context: { count: 0 },
  on: {
    inc: (ctx) => ({ count: ctx.count + 1 }),
    dec: (ctx) => ({ count: ctx.count - 1 })
  }
});

store.subscribe((snapshot) => {
  console.log(snapshot.context.count);
});

store.trigger.inc(); // count = 1

Store with React

import { useSelector } from '@xstate/store-react';

function Counter() {
  const count = useSelector(store, (state) => state.context.count);

  return (
    <div>
      <span>{count}</span>
      <button onClick={() => store.trigger.inc()}>+</button>
      <button onClick={() => store.trigger.dec()}>-</button>
    </div>
  );
}

Guards and Actions

const machine = setup({
  guards: {
    isPositive: ({ context }) => context.count > 0,
    canIncrement: ({ context }) => context.count < 10
  },
  actions: {
    logCount: ({ context }) => console.log('Count:', context.count)
  }
}).createMachine({
  context: { count: 0 },
  states: {
    active: {
      on: {
        INCREMENT: {
          guard: 'canIncrement',
          actions: ['increment', 'logCount']
        },
        DECREMENT: {
          guard: 'isPositive',
          actions: ['decrement', 'logCount']
        }
      }
    }
  }
});

Routable States (v5.28+)

const machine = createMachine({
  id: 'app',
  initial: 'home',
  states: {
    home: { id: 'home', route: {} },
    dashboard: {
      initial: 'overview',
      states: {
        overview: { id: 'overview', route: {} },
        settings: {
          id: 'settings',
          route: {
            guard: ({ context }) => context.role === 'admin'
          }
        }
      }
    }
  }
});

// Route directly to deeply nested state
actor.send({ type: 'xstate.route', to: '#settings' });

📖 Available References

• references/README.md - Complete documentation with examples, templates, and getting started guide
• references/issues.md - Recent GitHub issues including bugs, feature requests, and known problems
• references/releases.md - Detailed release notes with new features and fixes
• references/file_structure.md - Repository structure showing packages, examples, and source organization

💻 Working with This Skill

Common Tasks

• API Reference: Look in references/README.md for core functions and methods
• Framework Integration: Check packages section for React, Vue, Svelte adapters
• Troubleshooting: Review references/issues.md for known problems and workarounds
• Recent Changes: Use references/releases.md for version upgrade guidance

Key Packages

• xstate - Core state machine library
• @xstate/react - React hooks and utilities
• @xstate/vue - Vue composition functions
• @xstate/svelte - Svelte utilities
• @xstate/store - Simple state management
• @statelyai/inspect - Development tools

🔑 Key Concepts

State Machines vs Statecharts

• State Machine: Basic finite states with transitions
• Statechart: Extended with hierarchy, parallelism, guards, and actions

Actor Model

• Actor: Running instance of machine logic (like a store)
• System: Manages multiple actors and their communication
• Spawn: Create child actors dynamically

Setup vs createMachine

• setup(): Type-safe configuration with reusable actions/guards
• createMachine(): Direct machine definition, less type safety

XState Store vs XState

• XState: Full statecharts with complex logic
• @xstate/store: Simple state management for basic needs