Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/statelyai/xstate/llms.txt

Use this file to discover all available pages before exploring further.

This guide will walk you through creating your first state machine with XState. You’ll learn how to define states, handle events, and manage context.

​
Prerequisites

Make sure you have XState installed: 
npm install xstate

​
Build a toggle machine

Let’s create a simple toggle machine that switches between inactive and active states, and counts how many times it’s been activated.
1

Import XState functions

First, import the functions you’ll need from XState:
import { createMachine, createActor, assign } from 'xstate';
  • createMachine - Creates a state machine definition
  • createActor - Creates a running instance of the machine
  • assign - Updates the machine’s context (data)
2

Define the state machine

Create a state machine with two states and a counter:
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' }
      }
    }
  }
});
This machine:
  • Starts in the inactive state
  • Has a count in its context that tracks activations
  • Transitions to active when it receives a TOGGLE event
  • Increments the counter each time it enters the active state
  • Returns to inactive when it receives another TOGGLE event
3

Create an actor

An actor is a running instance of your state machine logic, like a store:
const toggleActor = createActor(toggleMachine);
The actor hasn’t started yet, so it won’t process events until you start it.
4

Subscribe to state changes

Subscribe to the actor to receive updates when the state changes:
toggleActor.subscribe((state) => {
  console.log(state.value, state.context);
});
The state object contains:
  • state.value - The current state name
  • state.context - The current context data
5

Start the actor

Start the actor to begin processing:
toggleActor.start();
// => logs 'inactive', { count: 0 }
When you start the actor, it immediately emits its initial state.
6

Send events

Send events to trigger state transitions:
toggleActor.send({ type: 'TOGGLE' });
// => logs 'active', { count: 1 }

toggleActor.send({ type: 'TOGGLE' });
// => logs 'inactive', { count: 1 }
Each time you send the TOGGLE event:
  • The machine transitions to the next state
  • The counter increments when entering the active state
  • Subscribers are notified of the state change

​
Complete example

Here’s the complete code: 
import { createMachine, createActor, assign } from 'xstate';

// State machine
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' }
      }
    }
  }
});

// Actor (instance of the machine logic, like a store)
const toggleActor = createActor(toggleMachine);
toggleActor.subscribe((state) => console.log(state.value, state.context));
toggleActor.start();
// => logs 'inactive', { count: 0 }

toggleActor.send({ type: 'TOGGLE' });
// => logs 'active', { count: 1 }

toggleActor.send({ type: 'TOGGLE' });
// => logs 'inactive', { count: 1 }

​
Understanding the core concepts

​
States

States represent the different modes your application can be in. In this example:
  • inactive - The toggle is off
  • active - The toggle is on
Your machine can only be in one state at a time, which prevents impossible states.

​
Events

Events trigger transitions between states. Events are objects with a type property: 
{ type: 'TOGGLE' }

​
Context

Context is the data that persists across state transitions. Use assign to update context: 
entry: assign({ count: ({ context }) => context.count + 1 })

​
Actors

Actors are running instances of your state machine logic. They:
  • Process events
  • Emit state changes
  • Can be subscribed to for updates
  • Can spawn other actors
Think of a state machine as a blueprint, and an actor as a running instance of that blueprint, similar to how a class is a blueprint and an object is an instance.

​
Next steps

Core concepts

Dive deeper into state machines and actors

Hierarchical states

Learn about hierarchical and parallel states

Actions

Execute side effects in your state machines

Stately Studio

Visualize and edit your state machines

Build docs developers (and LLMs) love

Get started for freeTalk to us