Xstate
State machines, statecharts, and actors for complex logic
Install / Use
/learn @statelyai/XstateREADME
XState is a state management and orchestration solution for JavaScript and TypeScript apps. It has zero dependencies, and is useful for frontend and backend application logic.
It uses event-driven programming, state machines, statecharts, and the actor model to handle complex logic in predictable, robust, and visual ways. XState provides a powerful and flexible way to manage application and workflow state by allowing developers to model logic as actors and state machines.
✨ Create state machines visually in Stately Studio → state.new
➡️ Create state machines with the Stately Editor
🖥 Download our VS Code extension
📑 Inspired by the SCXML specification
💬 Chat on the Stately Discord Community
✍️ Browse through the many XState examples
Sponsors
Special thanks to the sponsors who support this open-source project:
<img src="https://opencollective.com/xstate/tiers/backer/badge.svg?label=sponsors&color=brightgreen" /> <a href="https://transloadit.com/?utm_source=xstate&utm_medium=referral&utm_campaign=sponsorship&utm_content=github"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://assets.transloadit.com/assets/images/sponsorships/logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://assets.transloadit.com/assets/images/sponsorships/logo-default.svg"> <img src="https://assets.transloadit.com/assets/images/sponsorships/logo-default.svg" alt="Transloadit Logo"> </picture> </a>Templates
Get started by forking one of these templates on CodeSandbox:
<table> <thead> <tr><th>Template</th><th></th></tr> </thead> <tbody> <tr> <td>🤖 XState Template (CodeSandbox)
- XState v5
- TypeScript
- No framework
⚛️ XState + React Template (CodeSandbox)
- React
- XState v5
- TypeScript
💚 XState + Vue Template (CodeSandbox)
- Vue
- XState v5
- TypeScript
🧡 XState + Svelte Template (CodeSandbox)
- Svelte
- XState v5
- TypeScript
Super quick start
npm install xstate
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 }
Stately Studio
- Visually create, edit, and collaborate on state machines
- Export to many formats, including XState v5
- Test path & documentation autogeneration
- Deploy to Stately Sky
- Generate & modify machines with Stately AI
Why?
Statecharts are a formalism for modeling stateful, reactive systems. This is useful for declaratively describing the behavior of your application, from the individual components to the overall application logic.
Read 📽 the slides (🎥 video) or check out these resources for learning about the importance of finite state machines and statecharts in user interfaces:
- Statecharts - A Visual Formalism for Complex Systems by David Harel
- The World of Statecharts by Erik Mogensen
Packages
| Package | Description |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 🤖 xstate | Core finite state machine and statecharts library + interpreter, including graph traversal and model-based testing utilities |
| ⚛️ @xstate/react | React hooks and utilities for using XState in React applications |
| 💚 @xstate/vue | Vue composition functions and utilities for using XState in Vue applications |
| 🎷 @xstate/svelte | Svelte utilities for using XState in Svelte applications |
| 🥏 @xstate/solid | Solid hooks and utilities for using XState in Solid applications |
| 🔍 @statelyai/inspect | Inspection utilities for XState |
| 🏪 @xstate/store | Small library for simple state management |
Finite State Machines
<table> <thead><tr><th>Code</th><th>Statechart</th></tr></thead> <tbody> <tr> <td>import { createMachine, createActor } from 'xstate';
const lightMachine = createMachine({
id: 'light',
initial: 'green',
states: {
green: {
on: {
TIMER: 'yellow'
}
},
yellow: {
on: {
TIMER: 'red'
}
},
red: {
on: {
TIMER: 'green'
}
}
}
});
const actor = createActor(lightMachine);
actor.subscribe((state) => {
console.log(state.value);
});
actor.start();
// logs 'green'
actor.send({ type: 'TIMER' });
// logs 'yellow'
Hierarchical (Nested) State Machines
<table> <thead><tr><th>Code</th><th>Statechart</th></tr></thead> <tbody> <tr> <td>import { createMachine, createActor } from 'xstate';
const pedestrianStates = {
initial: 'walk',
states: {
walk: {
on: {
PED_TIMER: 'wait'
}
},
wait: {
on: {
PED_TIMER: 'stop'
}
},
stop: {}
}
};
const lightMachine = createMachine({
id: 'light',
initial: 'green',
states: {
green: {
on: {
TIMER: 'yellow'
}
},
yellow: {
on: {
TIMER: 'red'
}
},
red: {
on: {
TIMER: 'green'
},
...pedestrianStates
}
}
});
const a
