Want to learn more about the concepts of state machines? [Check out our introduction to state machines and statecharts](state-machines-and-statecharts).
## States [#states]
In Stately’s editor, the rounded rectangle boxes are states. There are a few different types of states:
* **Normal** states don’t have any special properties.
* [**Initial states**](#initial-states) are the first states the machine enters when it starts.
* [**Final states**](#final-states) are the last states the machine enters before it stops.
* [**Parent states**](#parent-and-child-states) can contain more states, known as child states.
* [**Parallel states**](#parallel-states) are parent states that have multiple child states that are all active at the same time.
* [**History states**](#history-states) are parent states that remember which child state was active when the parent state was exited and re-enter that child state when the parent state is re-entered.
In the future, we plan to provide configurable embeds with copy-and-paste code.
If you want us to prioritize improving embed mode, please [upvote it on our feedback page](https://github.com/statelyai/feedback/issues/94).
## URL parameters, including color mode [#url-parameters-including-color-mode]
The embed URL has some of the same parameters as the [machine URL](url).
* **machineId**: the unique ID for the machine. For example, `machineId=491a4c60-5300-4e22-92cf-8a32a8ffffca`
* **mode**: the current machine mode. For example, `mode=Design` or `mode=Simulate`
* **colorMode**: the color mode for the embedded machine. For example, `colorMode=light` or `colorMode=dark`
By default, the color mode will be the same as your chosen Stately Studio color mode. Add `&colorMode=light` or `&colorMode=dark` to the URL to force that color mode.
# Event emitter (/docs/event-emitter)
*Since XState version 5.9.0*
State machines and other types of actor logic in XState have the ability to emit events. This allows external event handlers to be notified of specific events.
With state machines, you can emit events using the `emit(event)` action creator.
```ts
import { setup, emit } from 'xstate';
const machine = setup({
actions: {
// [!code highlight:1]
emitEvent: emit({ type: 'notification' }),
},
}).createMachine({
// ...
on: {
someEvent: {
// [!code highlight:1]
actions: { type: 'emitEvent' },
},
},
});
const actor = createActor(machine);
// [!code highlight:3]
actor.on('notification', (event) => {
console.log('Notification received!', event);
});
actor.start();
actor.send({ type: 'someEvent' });
// Logs:
// "Notification received!"
// { type: "notification" }
```
## Emitting events from actor logic [#emitting-events-from-actor-logic]
For promise actors, transition actors, observable actors, and callback actors, you can use the `emit` method from the arguments to emit events.
**Promise actors**
```ts
import { fromPromise } from 'xstate';
// [!code highlight:1]
const logic = fromPromise(async ({ emit }) => {
// ...
// [!code highlight:4]
emit({
type: 'emitted',
msg: 'hello',
});
// ...
});
```
**Transition actors**
```ts
import { fromTransition } from 'xstate';
// [!code highlight:1]
const logic = fromTransition((state, event, { emit }) => {
// ...
// [!code highlight:4]
emit({
type: 'emitted',
msg: 'hello',
});
// ...
return state;
}, {});
```
**Observable actors**
```ts
import { fromObservable } from 'xstate';
// [!code highlight:1]
const logic = fromObservable(({ emit }) => {
// ...
// [!code highlight:4]
emit({
type: 'emitted',
msg: 'hello',
});
// ...
});
```
**Callback actors**
```ts
import { fromCallback } from 'xstate';
// [!code highlight:1]
const logic = fromCallback(({ emit }) => {
// ...
// [!code highlight:4]
emit({
type: 'emitted',
msg: 'hello',
});
// ...
});
```
## Emit action creator [#emit-action-creator]
The emit action is a special action that *emits* an event to any external event handlers from state machine logic. The emitted event can be statically or dynamically defined:
```ts
import { setup, emit } from 'xstate';
const machine = setup({
actions: {
// [!code highlight:5]
// Emitting a statically-defined event
emitStaticEvent: emit({
type: 'someStaticEvent',
data: 42,
}),
// [!code highlight:5]
// Emitting a dynamically-defined event based on context
emitDynamicEvent: emit(({ context }) => ({
type: 'someDynamicEvent',
data: context.someData,
})),
},
}).createMachine({
// ...
on: {
someEvent: {
actions: [{ type: 'emitStaticEvent' }, { type: 'emitDynamicEvent' }],
},
},
});
```
## Event handlers [#event-handlers]
You can attach event handlers to the actor to listen for emitted events by using `actor.on(event, handler)`:
```ts
const someActor = createActor(someMachine);
// [!code highlight:4]
someActor.on('someEvent', (emittedEvent) => {
// Handle the emitted event
console.log(emittedEvent);
});
someActor.start();
```
The `actor.on(…)` method returns a subscription object. You can call `.unsubscribe()` on it to remove the handler:
```ts
const someActor = createActor(someMachine);
// [!code highlight:4]
const subscription = someActor.on('someEvent', (emittedEvent) => {
// Handle the emitted event
console.log(emittedEvent);
});
someActor.start();
// ...
// [!code highlight:2]
// Stop listening for events
subscription.unsubscribe();
```
## Wildcard event handlers [#wildcard-event-handlers]
You can listen for *any* emitted event by listening for the wildcard `'*'`:
```ts
const someActor = createActor(someMachine);
actor.on('*', (emitted) => {
console.log(emitted); // Any emitted event
});
```
The `emitted` event will be typed as the union of all possible events that can be emitted from the machine.
## TypeScript [#typescript]
You can strongly type emitted events by defining the emitted event types in the `types.emitted` property of the `setup(…)` function:
```ts
import { setup, emit, createActor } from 'xstate';
const machine = setup({
types: {
// [!code highlight:3]
emitted: {} as
| { type: 'notification'; message: string }
| { type: 'error'; error: Error },
// ...
},
}).createMachine({
// ...
on: {
someEvent: {
actions: [
// [!code highlight:2]
// Strongly typed emitted event
emit({ type: 'notification', message: 'Hello' }),
],
},
},
});
const actor = createActor(machine);
// [!code highlight:4]
// Strongly typed event handler
actor.on('notification', (event) => {
console.log(event.message); // string
});
```
# Eventless (always) transitions (/docs/eventless-transitions)
**Eventless transitions** are transitions that happen without an explicit event. These transitions are *always* taken when the transition is enabled.
Eventless transitions are specified on the `always` state property and often referred to as “always” transitions.
You can easily visualize and simulated eventless transitions in Stately’s editor. [Read more about eventless transitions in Stately’s editor](/docs/editor-states-and-transitions/#eventless-always-transitions).
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
states: {
form: {
initial: 'valid',
states: {
valid: {},
invalid: {},
},
// [!code highlight:4]
always: {
guard: 'isValid',
target: 'valid',
},
},
},
});
```
## Eventless transitions and guards [#eventless-transitions-and-guards]
Eventless transitions are taken immediately after normal transitions are taken. They are only taken if enabled, for example, if their [guards](guards) are true. This makes eventless transitions helpful in doing things when some condition is true.
## Avoid infinite loops [#avoid-infinite-loops]
Since unguarded “always” transitions always run, you should be careful not to create an infinite loop. XState will help guard against most infinite loop scenarios.
Eventless transitions with no `target` nor `guard` will cause an infinite loop. Transitions using `guard` and `actions` may run into an infinite loop if its `guard` keeps returning true.
You should define eventless transitions either with:
* `target`
* `guard` + `target`
* `guard` + `actions`
* `guard` + `target` + `actions`
If `target` is declared, the value should differ from the current state node.
## When to use [#when-to-use]
Eventless transitions can be helpful when a state change is necessary, but there is no specific trigger for that change.
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
id: 'kettle',
initial: 'lukewarm',
context: {
temperature: 80,
},
states: {
lukewarm: {
on: {
boil: { target: 'heating' },
},
},
heating: {
always: {
guard: ({ context }) => context.temperature > 100,
target: 'boiling',
},
},
boiling: {
entry: ['turnOffLight'],
always: {
guard: ({ context }) => context.temperature <= 100,
target: 'heating',
},
},
},
on: {
'temp.update': {
actions: ['updateTemperature'],
},
},
});
```
**XState v5 requires TypeScript version 5.0 or greater.**
For best results, use the latest TypeScript version. [Read more about XState and TypeScript](typescript)
Eventless transitions can potentially be enabled by any event, so the `event` type is the union of all possible events.
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
types: {} as {
events: { type: 'greet'; message: string } | { type: 'submit' };
},
// ...
always: {
actions: ({ event }) => {
event.type; // 'greet' | 'submit'
},
guard: ({ event }) => {
event.type; // 'greet' | 'submit'
return true;
},
},
});
```
## Eventless transitions cheatsheet [#eventless-transitions-cheatsheet]
### Cheatsheet: root eventless (always) transition [#cheatsheet-root-eventless-always-transition]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
always: {
guard: 'isValid',
actions: ['doSomething'],
},
// ...
});
```
### Cheatsheet: state eventless (always) transition [#cheatsheet-state-eventless-always-transition]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
initial: 'start',
states: {
start: {
always: {
guard: 'isValid',
target: 'otherState',
},
},
otherState: {
/* ... */
},
},
});
```
# XState examples (/docs/examples)
XState v5 examples are also available in the [`/examples` directory](https://github.com/statelyai/xstate/tree/main/examples). Many of the examples have a CodeSandbox link where you can run the example in your browser.
## Simple fetch example [#simple-fetch-example]
A simple fetch example built with:
* XState v5
* Parcel
* [Simple fetch example on GitHub](https://github.com/statelyai/xstate/tree/main/examples/fetch)
* [Simple fetch example on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/fetch)
## 7GUIs counter (React) [#7guis-counter-react]
An implementation of the [7GUIs counter](https://eugenkiss.github.io/7guis/tasks/#counter) built with:
* XState v5
* React
* TypeScript
* Vite
* [7GUIs counter (React) on GitHub](https://github.com/statelyai/xstate/tree/main/examples/7guis-counter-react)
* [7GUIs counter (React) on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/react-7guis-counter)
## 7GUIs temperature (React) [#7guis-temperature-react]
This is an implementation of the [7GUIs temperature converter](https://eugenkiss.github.io/7guis/tasks#temp) built with:
* XState v5
* React
* TypeScript
* Vite
* [7GUIs temperature (React) on GitHub](https://github.com/statelyai/xstate/tree/main/examples/7guis-temperature-react)
* [7GUIs temperature (React) on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/react-7guis-temperature)
## Simple list (React) [#simple-list-react]
A React list built with:
* XState v5
* React
* TypeScript
* Vite
* [Simple list (React) on GitHub](https://github.com/statelyai/xstate/tree/main/examples/friends-list-react)
* [Simple list (React) on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/react-list)
## Stopwatch [#stopwatch]
A simple stopwatch built with:
* XState v5
* TypeScript
* Vite
* [Stopwatch on GitHub](https://github.com/statelyai/xstate/tree/main/examples/stopwatch)
* [Stopwatch on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/stopwatch)
## Tic-tac-toe game (React) [#tic-tac-toe-game-react]
An implementation of tic-tac-toe built with:
* XState v5
* React
* TypeScript
* Vite
* [Tic-tac-toe game (React) on GitHub](https://github.com/statelyai/xstate/tree/main/examples/tic-tac-toe-react)
* [Tic-tac-toe game (React) on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/react-tic-tac-toe)
## Tiles game (React) [#tiles-game-react]
A simple tiles game built with:
* XState v5
* React
* TypeScript
* Vite
* [Tiles game (React) on GitHub](https://github.com/statelyai/xstate/tree/main/examples/tiles)
* [Tiles game (React) on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/tiles)
## TodoMVC (React) [#todomvc-react]
An implementation of [TodoMVC](https://todomvc.com/) built with:
* XState v5
* React
* TypeScript
* Vite
* [TodoMVC (React) on GitHub](https://github.com/statelyai/xstate/tree/main/examples/todomvc-react)
* [TodoMVC (React) on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/todomvc-react)
## Toggle [#toggle]
A simple toggle built with:
* XState v5
* TypeScript
* Vite
* [Toggle on GitHub](https://github.com/statelyai/xstate/tree/main/examples/toggle)
* [Toggle on CodeSandbox](https://codesandbox.io/p/sandbox/github/statelyai/xstate/tree/main/examples/toggle)
## Hello world workflow [#hello-world-workflow]
Serverless hello world workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Hello-World-Example) built with:
* XState v5
[Hello world workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-hello)
## Greeting workflow [#greeting-workflow]
Serverless greeting workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Greeting-Example) built with:
* XState v5
[Greeting workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-greeting)
## Event-based greeting workflow [#event-based-greeting-workflow]
Serverless event-based greeting workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Event-Based-Greeting-Example) built with:
* XState v5
[Event-based greeting workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-event-greeting)
## Solving math problems [#solving-math-problems]
Serverless math solving problem workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Solving-Math-Problems-Example) built with:
* XState v5
[Solving math problems on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-math-problem)
## Parallel execution workflow [#parallel-execution-workflow]
Serverless parallel execution workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Parallel-Execution-Example) built with:
* XState v5
[Parallel execution workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-parallel)
## Async function invocation workflow [#async-function-invocation-workflow]
Serverless async function invocation workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Async-Function-Invocation-Example) built with:
* XState v5
[Async function invocation workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-async-function)
## Async subflow invocation workflow [#async-subflow-invocation-workflow]
Serverless async subflow invocation workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Async-SubFlow-Invocation-Example) built with:
* XState v5
[Async subflow invocation workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-async-subflow)
## Event-based transitions (event-based switch) workflow [#event-based-transitions-event-based-switch-workflow]
Serverless event-based transitions workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Event-Based-Transitions-Example) built with:
* XState v5
[Event-based transitions workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-event-based)
## Applicant request decision workflow [#applicant-request-decision-workflow]
Serverless applicant request decision workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Applicant-Request-Decision-Example) built with:
* XState v5
[Applicant request decision workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-applicant-request)
## Provision orders (error handling) workflow [#provision-orders-error-handling-workflow]
Serverless provision orders (error handling) workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Provision-Orders-Example) built with:
* XState v5
[Provision orders (error handling) workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-provision-orders)
## Monitor job for completion (polling) workflow [#monitor-job-for-completion-polling-workflow]
Serverless monitor job for completion (polling) workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Monitor-Job-Example) built with:
* XState v5
[Monitor job for completion (polling) workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-monitor-job)
## Send CloudEvent on workflow completion [#send-cloudevent-on-workflow-completion]
Serverless send CloudEvent on workflow completion workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Send-CloudEvent-On-Workflow-Completion-Example) built with:
* XState v5
[Send CloudEvent on workflow completion on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-send-cloudevent)
## Monitor patient vital signs workflow [#monitor-patient-vital-signs-workflow]
Serverless monitor patient vital signs workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Monitor-Patient-Vital-Signs-Example) built with:
* XState v5
[Monitor patient vital signs workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-monitor-patient)
## Finalize college application workflow [#finalize-college-application-workflow]
Serverless finalize college application workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Finalize-College-Application-Example) built with:
* XState v5
[Finalize college application workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-finalize-college-app)
## Perform customer credit check workflow [#perform-customer-credit-check-workflow]
Serverless perform customer credit check workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Perform-Customer-Credit-Check-Example) built with:
* XState v5
[Perform customer credit check workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-credit-check)
## Handle car auction bids (scheduled start) workflow [#handle-car-auction-bids-scheduled-start-workflow]
Serverless handle car auction bids (scheduled start) workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Handle-Car-Auction-Bids-Example) built with:
* XState v5
[Handle car auction bids (scheduled start) workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-car-auction-bids)
## Check inbox periodically (cron-based workflow start) [#check-inbox-periodically-cron-based-workflow-start]
Serverless check inbox periodically (cron-based workflow start) from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Check-Inbox-Periodically) built with:
* XState v5
[Check inbox periodically (cron-based workflow start) on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-check-inbox)
## Event-based service workflow [#event-based-service-workflow]
Serverless event-based service workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Event-Based-Service-Invocation) built with:
* XState v5
[Event-based service workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-event-based-service)
## Reusing function and event definitions workflow [#reusing-function-and-event-definitions-workflow]
Serverless reusing function and event definitions workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Reusing-Function-And-Event-Definitions) built with:
* XState v5
[Reusing function and event definitions workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-reusing-functions)
## New patient onboarding (error checking and retries) workflow [#new-patient-onboarding-error-checking-and-retries-workflow]
Serverless new patient onboarding (error checking and retries) workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#new-patient-onboarding).
[New patient onboarding (error checking and retries) workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-new-patient-onboarding)
## Purchase order deadline (ExecTimeout) workflow [#purchase-order-deadline-exectimeout-workflow]
Serverless purchase order deadline (ExecTimeout) workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#purchase-order-deadline) built with:
* XState v5
[Purchase order deadline (ExecTimeout) workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-purchase-order-deadline)
## Accumulate room readings and create timely reports (ExecTimeout and KeepActive) workflow [#accumulate-room-readings-and-create-timely-reports-exectimeout-and-keepactive-workflow]
Serverless accumulate room readings and create timely reports (ExecTimeout and KeepActive) workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#accumulate-room-readings) built with:
* XState v5
[Accumulate room readings and create timely reports (ExecTimeout and KeepActive) workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-accumulate-room-readings)
## Car vitals checks (SubFlow Repeat) workflow [#car-vitals-checks-subflow-repeat-workflow]
Store a single bid when the car auction is active.
Serverless car vitals checks (SubFlow Repeat) workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#handle-car-auction-bids-example) built with:
* XState v5
[Car vitals checks (SubFlow Repeat) workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-car-vitals)
## Book lending workflow [#book-lending-workflow]
Serverless book lending workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#book-lending) built with:
* XState v5
[Book lending workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-book-lending)
## Filling a glass of water workflow [#filling-a-glass-of-water-workflow]
Serverless filling a glass of water workflow from the [CNCF Serverless Workflow examples](https://github.com/serverlessworkflow/specification/tree/main/examples#Filling-a-glass-of-water) built with:
* XState v5
[Filling a glass of water workflow on GitHub](https://github.com/statelyai/xstate/tree/main/examples/workflow-filling-water)
## More examples coming soon [#more-examples-coming-soon]
If you have any examples you want us to make, please [add a request to our feedback board](https://feedback.stately.ai/examples) or upvote an existing suggestion.
If you have an example you want to share, [contribute your example to the XState repository](https://github.com/statelyai/xstate/tree/main/examples#contributing-an-example).
# Export as code (/docs/export-as-code)
Exporting as code is useful if you want to use your machine with [XState](xstate) inside your codebase or if you want to duplicate your machine without using **Fork**.
You can now [generate a React app from your machine](generate-react).
Every feature of your state machine will be included in the code, except for [colors](colors) and [notes](annotations). Your last used export settings will be remembered next time you open the
You can also [import from code](import-from-code) from
### Export to CodeSandbox and StackBlitz [#export-to-codesandbox-and-stackblitz]
You can export your machines to CodeSandbox and StackBlitz from the
Wrap your Mermaid code in a fenced code block with the `mermaid` language identifier to [share your diagram on GitHub](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams) and [share your diagram on GitLab](https://handbook.gitlab.com/handbook/tools-and-tips/mermaid/).
# Embed Figma (/docs/figma)
You can embed Figma frames in your states to keep your design and code in sync. Embedded Figma frames will stay up to date with the latest changes in your Figma files. Figma frames are a special type of [asset](assets).
[In Nick’s blog post, read about how you can improve your team workflows with Stately and Figma](../../blog/2024-01-24-embed-figma/).
Embedding Figma frames is a premium feature of Stately Studio. [Check out the features on our Pro plan](studio-pro-plan), [Team plan](studio-team-plan), [Enterprise plan](studio-enterprise-plan) or [upgrade your existing plan](https://stately.ai/registry/billing).
You can easily visualize and simulate intial and final states in Stately's editor. [Read more about states in Stately's editor](/docs/editor-states-and-transitions).
```ts
import { createMachine } from 'xstate';
const feedbackMachine = createMachine({
id: 'feedback',
// Initial state
initial: 'prompt',
// Finite states
states: {
prompt: {
/* ... */
},
form: {
/* ... */
},
thanks: {
/* ... */
},
closed: {
/* ... */
},
},
});
```
You can combine finite states with [context](context), which make up the overall state of a machine:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
id: 'feedback',
context: {
name: '',
email: '',
feedback: '',
},
initial: 'prompt',
states: {
prompt: {
/* ... */
},
},
});
const feedbackActor = createActor(feedbackMachine).start();
// Finite state
console.log(feedbackActor.getSnapshot().value);
// logs 'prompt'
// Context ("extended state")
console.log(feedbackActor.getSnapshot().context);
// logs { name: '', email: '', feedback: '' }
```
## Initial state [#initial-state]
The initial state is the state that the machine starts in. It is defined by the `initial` property on the machine config:
```ts
import { createMachine } from 'xstate';
const feedbackMachine = createMachine({
id: 'feedback',
// [!code highlight:2]
// Initial state
initial: 'prompt',
// Finite states
states: {
// [!code highlight:1]
prompt: {
/* ... */
},
// ...
},
});
```
[Read more about initial states](initial-states).
## State nodes [#state-nodes]
In XState, a **state node** is a finite state "nodes" that comprise the entire statechart tree. State nodes are defined on the `states` property of other state nodes, including the root machine config (which itself is a state node):
```ts
import { createMachine } from 'xstate';
// The machine is the root state node
const feedbackMachine = createMachine({
id: 'feedback',
initial: 'prompt',
// State nodes
states: {
// State node
prompt: {
/* ... */
},
// State node
form: {
/* ... */
},
// State node
thanks: {
/* ... */
},
// State node
closed: {
/* ... */
},
},
});
```
## Tags [#tags]
State nodes can have **tags**, which are string terms that help group or categorize the state node. For example, you can signify which state nodes represent states in which data is being loaded by using a "loading" tag, and determine if a state contains those tagged state nodes with `state.hasTag(tag)`:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
id: 'feedback',
initial: 'prompt',
states: {
prompt: {
tags: ['visible'],
// ...
},
form: {
tags: ['visible'],
// ...
},
thanks: {
tags: ['visible', 'confetti'],
// ...
},
closed: {
tags: ['hidden'],
},
},
});
const feedbackActor = createActor(feedbackMachine).start();
console.log(feedbackActor.getSnapshot().hasTag('visible'));
// logs true
```
Read more about [tags](tags).
## Meta [#meta]
Meta data is static data that describes relevant properties of a state node. You can specify meta data on the `.meta` property of any state node. This can be useful for displaying information about a state node in a UI, or for generating documentation.
The `state.meta` property collects the `.meta` data from all active state nodes and places them in an object with the state node's ID as the key and the `.meta` data as the value:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
id: 'feedback',
initial: 'prompt',
meta: {
title: 'Feedback',
},
states: {
prompt: {
meta: {
content: 'How was your experience?',
},
},
form: {
meta: {
content: 'Please fill out the form below.',
},
},
thanks: {
meta: {
content: 'Thank you for your feedback!',
},
},
closed: {},
},
});
const feedbackActor = createActor(feedbackMachine).start();
console.log(feedbackActor.getSnapshot().meta);
// logs the object:
// {
// feedback: {
// title: 'Feedback',
// },
// 'feedback.prompt': {
// content: 'How was your experience?',
// }
// }
```
## Transitions [#transitions]
Transitions are how you move from one finite state to another. They are defined by the `on` property on a state node:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
initial: 'prompt',
states: {
prompt: {
on: {
'feedback.good': {
target: 'thanks',
},
},
},
thanks: {
/* ... */
},
// ...
},
});
const feedbackActor = createActor(feedbackMachine).start();
console.log(feedbackActor.getSnapshot().value);
// logs 'prompt'
feedbackActor.send({ type: 'feedback.good' });
console.log(feedbackActor.getSnapshot().value);
// logs 'thanks'
```
Read more about [events and transitions](transitions).
## Targets [#targets]
A transition's `target` property defines where the machine should go when the transition is taken. Normally, it targets a sibling state node:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
initial: 'prompt',
states: {
prompt: {
on: {
'feedback.good': {
// [!code highlight:2]
// Targets the sibling `thanks` state node
target: 'thanks',
},
},
},
thanks: {
/* ... */
},
// ...
},
});
```
The `target` can also target a descendant of a sibling state node:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
initial: 'prompt',
states: {
prompt: {
on: {
'feedback.good': {
// [!code highlight:2]
// Targets the sibling `thanks.happy` state node
target: 'thanks.happy',
},
},
},
thanks: {
initial: 'normal',
states: {
normal: {},
// [!code highlight:1]
happy: {},
},
},
// ...
},
});
```
When the target state node is a descendant of the source state node, the source state node key can be omitted:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
// ...
states: {
closed: {
initial: 'normal',
states: {
normal: {},
keypress: {},
},
},
},
on: {
'feedback.close': {
// [!code highlight:2]
// Targets the descendant `closed` state node
target: '.closed',
},
'key.escape': {
// [!code highlight:2]
// Targets the descendant `closed.keypress` state node
target: '.closed.keypress',
},
},
});
```
When the state node doesn't change; i.e., the source and target state nodes are the same, the `target` property can be omitted:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
// ...
states: {
form: {
on: {
'feedback.update': {
// [!code highlight:2]
// No target defined – stay on the `form` state node
// Equivalent to `target: '.form'` or `target: undefined`
actions: 'updateForm',
},
},
},
},
});
```
State nodes can also be targeted by their `id` by prefixing the `target` with a `#` followed by the state node's `id`:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
initial: 'prompt',
states: {
// [!code highlight:3]
closed: {
id: 'finished',
},
// ...
},
on: {
'feedback.close': {
// [!code highlight:1]
target: '#finished',
},
},
});
```
## Identifying state nodes [#identifying-state-nodes]
States can be identified with a unique ID: `id: 'myState'`. This is useful for targeting a state from any other state, even if they have different parent states:
```ts
import { createMachine, createActor } from 'xstate';
const feedbackMachine = createMachine({
initial: 'prompt',
states: {
// ...
closed: {
// [!code highlight:1]
id: 'finished',
type: 'final',
},
// ...
},
on: {
'feedback.close': {
// [!code highlight:2]
// Target the `.closed` state by its ID
target: '#finished',
},
},
});
```
State IDs do not affect the `state.value`. In the above example, the `state.value` would still be `closed` even though the state node is identified as `#finished`.
## Other state types [#other-state-types]
In statecharts, there are other types of states:
* [Parent states (also known as compound states)](parent-states)
* [Parallel states](parallel-states)
* [History states](history-states)
* [Final states](final-states)
## Modeling states [#modeling-states]
When designing finite states for your state machine, follow these guidelines to create maintainable and effective state machines:
### Start simple and shallow [#start-simple-and-shallow]
* **Begin with minimal states**: Don't create multiple finite states until it becomes apparent that the behavior of your logic differs depending on some finite state it can be in.
* **Avoid premature optimization**: Start with basic states and add complexity only when necessary.
* **Prefer flat structures initially**: Deep nesting can be added later when patterns emerge.
### Identify distinct behaviors [#identify-distinct-behaviors]
* **Different behavior = different state**: Create separate states when the application behaves differently in response to the same event.
* **Same behavior = same state**: If multiple "states" handle events identically, they should probably be a single state.
* **Question impossible states**: Ask "can this combination of conditions exist?" If not, model them as separate states.
### Name states clearly [#name-states-clearly]
* **Use descriptive names**: State names should clearly describe what the machine is doing or what mode it's in.
* **Avoid technical jargon**: Use domain-specific language that stakeholders understand.
* **Be consistent**: Use consistent naming conventions across your state machines.
```ts
import { createMachine } from 'xstate';
// ❌ Poor naming
const machine = createMachine({
initial: 'state1',
states: {
state1: {}, // What does this represent?
state2: {}, // What does this represent?
error: {}, // Too generic
},
});
// ✅ Good naming
const authMachine = createMachine({
initial: 'signedOut',
states: {
signedOut: {},
signingIn: {},
signedIn: {},
authenticationFailed: {}, // Specific error state
},
});
```
### Model user workflows [#model-user-workflows]
* **Follow the user journey**: States should reflect the natural progression of user actions.
* **Consider all paths**: Include happy paths, error states, and edge cases.
* **Account for loading states**: Async operations often need intermediate states.
```ts
import { createMachine } from 'xstate';
const checkoutMachine = createMachine({
initial: 'cart',
states: {
cart: {
on: {
PROCEED: { target: 'shippingInfo' },
},
},
shippingInfo: {
on: {
CONTINUE: { target: 'paymentInfo' },
BACK: { target: 'cart' },
},
},
paymentInfo: {
on: {
SUBMIT: { target: 'processing' },
BACK: { target: 'shippingInfo' },
},
},
processing: {
on: {
SUCCESS: { target: 'confirmed' },
FAILURE: { target: 'paymentFailed' },
},
},
paymentFailed: {
on: {
RETRY: { target: 'paymentInfo' },
},
},
confirmed: {
type: 'final',
},
},
});
```
### Consider temporal aspects [#consider-temporal-aspects]
* **Time-sensitive states**: Model states that exist for specific durations.
* **Expiration handling**: Include states for handling timeouts and expirations.
* **Scheduled transitions**: Use delayed transitions for time-based state changes.
### Group related functionality [#group-related-functionality]
* **Use tags for categorization**: Group states by common characteristics.
* **Consider parent states**: When multiple states share common transitions, consider grouping them under a parent state.
* **Separate concerns**: Keep different domains or features in separate states.
```ts
import { createMachine } from 'xstate';
const appMachine = createMachine({
initial: 'loading',
states: {
loading: {
tags: ['busy'],
on: {
LOADED: { target: 'idle' },
ERROR: { target: 'error' },
},
},
idle: {
tags: ['interactive'],
on: {
START_WORK: { target: 'working' },
},
},
working: {
tags: ['busy', 'interactive'],
on: {
COMPLETE: { target: 'idle' },
CANCEL: { target: 'idle' },
},
},
error: {
tags: ['error'],
on: {
RETRY: { target: 'loading' },
},
},
},
});
```
### Handle edge cases [#handle-edge-cases]
* **Invalid states**: Model states for handling invalid or unexpected conditions.
* **Recovery states**: Provide ways to recover from error states.
* **Fallback behavior**: Include default states for unhandled scenarios.
### Validate state transitions [#validate-state-transitions]
* **Ensure all transitions make sense**: Every state transition should represent a valid business logic change.
* **Avoid circular dependencies**: Be careful of states that can endlessly transition between each other without purpose.
* **Consider guards**: Use guards to prevent invalid transitions even when events are received.
### Document state purpose [#document-state-purpose]
* **Use descriptions**: Add `.description` properties to explain complex states.
* **Include meta data**: Store relevant information about what each state represents.
* **Comment complex logic**: Explain why certain states exist and what they accomplish.
```ts
import { createMachine } from 'xstate';
const feedbackMachine = createMachine({
initial: 'prompt',
states: {
prompt: {
description: 'Waiting for user to indicate their satisfaction level',
meta: {
analytics: 'feedback_prompt_shown',
},
},
collectingDetails: {
description:
'User provided negative feedback, collecting detailed information',
meta: {
analytics: 'detailed_feedback_form_shown',
},
},
},
});
```
## Finite states and TypeScript [#finite-states-and-typescript]
**XState v5 requires TypeScript version 5.0 or greater.**
For best results, use the latest TypeScript version. [Read more about XState and TypeScript](typescript)
You can strongly type the finite states of your machine using the `setup(...)` function, which provides excellent TypeScript inference and autocompletion:
```ts
import { setup, createActor } from 'xstate';
const feedbackMachine = setup({
types: {
context: {} as { feedback: string; rating: number },
events: {} as
| { type: 'feedback.good' }
| { type: 'feedback.bad' }
| { type: 'feedback.submit' },
},
}).createMachine({
id: 'feedback',
initial: 'prompt',
context: {
feedback: '',
rating: 0,
},
states: {
prompt: {
on: {
'feedback.good': { target: 'thanks' },
'feedback.bad': { target: 'form' },
},
},
form: {
on: {
'feedback.submit': { target: 'thanks' },
},
},
thanks: {
type: 'final',
},
},
});
const feedbackActor = createActor(feedbackMachine).start();
// ✅ Type-safe and autocompletes
const currentState = feedbackActor.getSnapshot();
// ✅ `state.matches(...)` is type-safe with autocompletion
if (currentState.matches('prompt')) {
// TypeScript knows we're in the 'prompt' state
}
// ✅ All state values have autocompletion
const isFormState = currentState.matches('form');
const isThanksState = currentState.matches('thanks');
// ✅ `state.value` is also strongly typed
const stateValue = currentState.value; // 'prompt' | 'form' | 'thanks'
```
When using `setup(...).createMachine(...)`, TypeScript provides:
* **Type-safe state matching**: `state.matches(...)` with autocompletion for all possible state values
* **Strongly-typed state values**: `state.value` is typed as a union of all possible state names
* **Type-safe context**: Full type inference for `state.context`
* **Type-safe events**: `actor.send(...)` only accepts defined event types
## Finite states cheatsheet [#finite-states-cheatsheet]
### Cheatsheet: create finite states [#cheatsheet-create-finite-states]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
id: 'feedback',
initial: 'prompt',
states: {
prompt: {},
form: {},
thanks: {},
closed: {},
},
});
```
### Cheatsheet: finite states with transitions [#cheatsheet-finite-states-with-transitions]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
initial: 'prompt',
states: {
prompt: {
on: {
'feedback.good': { target: 'thanks' },
'feedback.bad': { target: 'form' },
},
},
form: {
on: {
'feedback.submit': { target: 'thanks' },
},
},
thanks: {},
},
});
```
### Cheatsheet: read current state [#cheatsheet-read-current-state]
```ts
import { createActor } from 'xstate';
const actor = createActor(machine).start();
const state = actor.getSnapshot();
// Read state value
console.log(state.value); // e.g., 'prompt'
// Check if in specific state
const isPromptState = state.matches('prompt');
// Check multiple states
const isFormOrThanks = state.matches('form') || state.matches('thanks');
```
### Cheatsheet: states with tags [#cheatsheet-states-with-tags]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
initial: 'prompt',
states: {
prompt: {
tags: ['visible', 'interactive'],
},
form: {
tags: ['visible', 'interactive'],
},
thanks: {
tags: ['visible', 'success'],
},
closed: {
tags: ['hidden'],
},
},
});
// Check tags
const state = actor.getSnapshot();
const isVisible = state.hasTag('visible');
const isInteractive = state.hasTag('interactive');
```
### Cheatsheet: states with meta data [#cheatsheet-states-with-meta-data]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
initial: 'prompt',
states: {
prompt: {
meta: {
title: 'How was your experience?',
component: 'PromptView',
},
},
form: {
meta: {
title: 'Tell us more',
component: 'FormView',
},
},
},
});
// Read meta data
const state = actor.getSnapshot();
console.log(state.getMeta());
```
### Cheatsheet: target states by ID [#cheatsheet-target-states-by-id]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
initial: 'start',
states: {
start: {
on: {
FINISH: { target: '#completed' },
},
},
process: {
states: {
step1: {},
step2: {},
},
},
done: {
id: 'completed',
type: 'final',
},
},
});
```
### Cheatsheet: strongly-typed finite states [#cheatsheet-strongly-typed-finite-states]
```ts
import { setup } from 'xstate';
const machine = setup({
types: {
context: {} as { count: number },
events: {} as { type: 'increment' } | { type: 'decrement' },
},
}).createMachine({
initial: 'idle',
context: { count: 0 },
states: {
idle: {
on: {
increment: { target: 'active' },
},
},
active: {
on: {
decrement: { target: 'idle' },
},
},
},
});
// Type-safe state matching
const state = actor.getSnapshot();
const isIdle = state.matches('idle'); // ✅ Autocompletes
const stateValue = state.value; // ✅ 'idle' | 'active'
```
# Function Actors (/docs/function-actors)
# Generate with AI (/docs/generate-flow)
**Generate with AI** is an experimental feature that helps you auto-create machines from text descriptions. You can generate a flow for a new machine or use the flow description to describe how you want to modify your current flow.
Community users can try generate flow with a limited number of generations each month. [Upgrade your existing plan](https://stately.ai/registry/billing) to get many more generations.
**Generate with AI** is a premium feature of Stately Studio. [Check out the features on our Pro plan](studio-pro-plan), [Team plan](studio-team-plan), [Enterprise plan](studio-enterprise-plan) or [upgrade your existing plan](https://stately.ai/registry/billing).
You have a limited number of generations available to use each month. The number of available generations is reset at the beginning of each calendar month.
There are many reasons you might want to generate your flows, including:
* You have a complex machine in mind and want to get started quickly
* You want an example of a state machine for a particular flow
* You’re new and want to get an idea of how you can model state machines
Community users can try **Generate React app** with a limited number of generations each month. [Upgrade your existing plan](https://stately.ai/registry/billing).
**Generate React app** is a premium feature of Stately Studio. [Check out the features on our Pro plan](studio-pro-plan), [Team plan](studio-team-plan), [Enterprise plan](studio-enterprise-plan) or [upgrade your existing plan](https://stately.ai/registry/billing).
You have a limited number of generations available to use each month. The number of available generations is reset at the beginning of each calendar month.
## Enhance app [#enhance-app]
Use the **Enhance app** button to generate an enhanced user interface after generating your React app. Once generated, the dropdown menu in the top right of the modal gives you options to preview three different versions of your enhanced app, as well as the default app generated before the enhancement.
When you use **Enhance app**, your state machine and generated React app are sent to OpenAI to generate the enhanced app.
# Generate test paths (/docs/generate-test-paths)
You can generate test path code for your state machines from the
**Generate test paths** is a premium feature of Stately Studio. [Check out the features on our Pro plan](studio-pro-plan), [Team plan](studio-team-plan), [Enterprise plan](studio-enterprise-plan) or [upgrade your existing plan](https://stately.ai/registry/billing).
## Path generation strategy [#path-generation-strategy]
You can choose between two path generation strategies:
* **Shortest path**: Generate paths that cover the shortest possible paths through your state machine and minimize the number of actions required to test functionality.
* **Simplest path**: Generate paths that cover the simple paths, without repeated states, through your state machine and help verify that basic functionality is working as expected.
## Testing frameworks [#testing-frameworks]
Generate test paths currently supports [Playwright](https://playwright.dev/) and custom testing framework formats. We plan to add more testing frameworks (including Puppeteer, Cypress, and even other languages) in the future.
## Options [#options]
* **Reduce duplicate paths** generates fewer paths that also cover other paths.
* **Prefer transition coverage** generates paths that cover all transitions in your state machine.
* **Highlight paths** enables highlighting the paths on the canvas when you hover over its test path description.
* **AI-generated test titles** (experimental) generates more readable test titles based on your state machine. AI-generated test titles send your state machine to OpenAI to generate the titles.
# Glossary (/docs/glossary)
This glossary is an alphabetical guide to the most common terms in statecharts and state machines.
Looking for more detailed information on these concepts? [Read the introduction to state machines and statecharts](state-machines-and-statecharts).
## Actions [#actions]
An [action](actions) is an effect that is executed during a state transition. Actions are “fire-and-forget effects”; once the machine has fired the action, it moves on and forgets the action.
## Actors [#actors]
When you run a state machine, it becomes an [actor](actors), which is a running process that can receive events, send events, and change its behavior based on the events it receives, which can cause effects outside of the actor.
## After transitions [#after-transitions]
See [delayed transitions](#delayed-transitions).
## Always transitions [#always-transitions]
See [eventless transitions](#eventless-transitions).
## Compound states [#compound-states]
See [parent and child states](#parent-and-child-states).
## Context [#context]
[Context](context) is the place that contextual data is stored in a state machine actor.
## Delayed transitions [#delayed-transitions]
[Delayed transitions](delayed-transitions) are transitions that only happen after a specified interval of time. If another event happens before the end of the timer, the transition doesn’t complete. Delayed transitions are labeled “after” and often referred to as “after” transitions.
## Eventless transitions [#eventless-transitions]
[Eventless transitions](eventless-transitions) are transitions without events. These transitions are *always* taken after any transition in their state is enabled. No event is necessary to trigger the transition. Eventless transitions are labeled “always” and often referred to as “always” transitions.
## Final state [#final-state]
When a machine reaches the [final state](final-states), it can no longer receive any events, and anything running inside it is canceled and cleaned up. A machine can have multiple final states or no final states.
## Guards [#guards]
A [guard](guards) is a condition that the machine checks when it goes through an event. If the condition is true, the machine follows the transition to the next state. If the condition is false, the machine follows the rest of the conditions to the next state. Any transition can be a guarded transition.
## History state [#history-state]
A [history state](history-states) returns the parent state to its most recently active child state.
## Initial state [#initial-state]
When a state machine starts, it enters the [**initial state**](initial-states) first. A machine can only have one top-level initial state.
## Invoked actors [#invoked-actors]
An [invoked actor](actors) is an actor that can execute its own actions and communicate with the machine. These invoked actors are started in a state and stopped when the state is exited.
## Parallel states [#parallel-states]
A [parallel state](parallel-states) is a state separated into multiple regions of child states, where each region is active simultaneously.
## Parent and child states [#parent-and-child-states]
States can contain more states, also known as [child states](parent-states). These child states are only active when the parent state is active. Child states are nested inside their parent states. Parent states are also known as compound states.
## States [#states]
A [state](states) describes the status of the machine. A state can be as simple as *active* and *inactive*. These states are finite; the machine can only move through the pre-defined states. A state machine can only be in one state at a time.
## Statecharts [#statecharts]
[Statecharts](state-machines-and-statecharts) are a visual extension to state machines enabling you to model more complex logic, including hierarchy, concurrency, and communication.
## State machines [#state-machines]
A [state machine](state-machines-and-statecharts) is a model that describes how the state of a process transitions to another state when an event occurs. State machines make building reliable software easier because they prevent impossible states and undesired transitions. When you run a state machine, it becomes an [actor](actors).
## Transitions and events [#transitions-and-events]
A machine moves from state to state through [transitions](transitions). Transitions are caused by events; when an event happens, the machine transitions to the next state. Transitions are “deterministic”; each combination of state and event always points to the same next state.
# Graph & Paths (/docs/graph)
The graph utilities are now included in the main `xstate` package. Import from `xstate/graph` instead of the deprecated `@xstate/graph` package.
State machines can be represented as directed graphs, where states are nodes and transitions are edges. XState provides utilities to traverse these graphs and generate **paths**: sequences of events that transition a machine from one state to another.
## Why use path generation? [#why-use-path-generation]
Path generation is useful for:
* **Model-based testing** - automatically generate test cases that cover all reachable states and transitions
* **Visualization** - understand the structure and flow of complex machines
* **Validation** - verify all states are reachable and all transitions are exercised
* **Documentation** - generate human-readable sequences of user flows
## Quick start [#quick-start]
```ts
import { createMachine } from 'xstate';
import { getShortestPaths, getSimplePaths } from 'xstate/graph';
const machine = createMachine({
initial: 'a',
states: {
a: {
on: { NEXT: 'b', SKIP: 'c' }
},
b: {
on: { NEXT: 'c' }
},
c: { type: 'final' }
}
});
const shortestPaths = getShortestPaths(machine);
// - a
// - a -> b
// - a -> c (via SKIP, not through b)
const simplePaths = getSimplePaths(machine);
// - a
// - a -> b
// - a -> b -> c
// - a -> c (via SKIP)
```
## Core concepts [#core-concepts]
### Paths and steps [#paths-and-steps]
A **path** represents a sequence of transitions from one state to another. Each path contains:
* `state` - the final state reached by this path
* `steps` - array of steps taken to reach that state
A **step** represents a single transition:
* `state` - the state before this transition
* `event` - the event that triggered the transition
```ts
// Example path structure
{
// The final state reached by this path
state: { value: 'thanks', context: {} },
// The steps taken to reach this state
steps: [
{ state: { value: 'question' }, event: { type: 'CLICK_BAD' } },
{ state: { value: 'form' }, event: { type: 'SUBMIT' } }
]
}
```
### Shortest vs simple paths [#shortest-vs-simple-paths]
**Shortest paths** use Dijkstra's algorithm to find the minimum number of transitions to reach each state. Use shortest paths when you want:
* One efficient path to each state
* Minimal test cases for state coverage
* Quick traversal verification
**Simple paths** use depth-first search to find all possible non-cyclic paths. Use simple paths when you want:
* Complete transition coverage
* All possible user flows
* Exhaustive testing
## `getShortestPaths(logic, options?)` [#getshortestpathslogic-options]
Returns the shortest path from the initial state to every reachable state.
```ts
import { createMachine } from 'xstate';
import { getShortestPaths } from 'xstate/graph';
const feedbackMachine = createMachine({
id: 'feedback',
initial: 'question',
states: {
question: {
on: {
CLICK_GOOD: { target: 'thanks' },
CLICK_BAD: { target: 'form' },
CLOSE: { target: 'closed' }
}
},
form: {
on: {
SUBMIT: { target: 'thanks' },
CLOSE: { target: 'closed' }
}
},
thanks: {
on: {
CLOSE: { target: 'closed' }
}
},
closed: {
type: 'final'
}
}
});
const paths = getShortestPaths(feedbackMachine);
// Returns array of paths:
// [
// { state: 'question', steps: [] },
// { state: 'thanks', steps: [{ state: 'question', event: { type: 'CLICK_GOOD' } }] },
// { state: 'form', steps: [{ state: 'question', event: { type: 'CLICK_BAD' } }] },
// { state: 'closed', steps: [{ state: 'question', event: { type: 'CLOSE' } }] }
// ]
```
Notice that reaching `closed` from `thanks` (2 steps) is not included because there's a shorter path directly from `question` (1 step).
## `getSimplePaths(logic, options?)` [#getsimplepathslogic-options]
Returns all simple (non-cyclic) paths from the initial state to every reachable state.
```ts
import { getSimplePaths } from 'xstate/graph';
const paths = getSimplePaths(feedbackMachine);
// Returns many more paths, including:
// - question → thanks (via CLICK_GOOD)
// - question → form → thanks (via CLICK_BAD, SUBMIT)
// - question → thanks → closed (via CLICK_GOOD, CLOSE)
// - question → form → thanks → closed (via CLICK_BAD, SUBMIT, CLOSE)
// - question → form → closed (via CLICK_BAD, CLOSE)
// - question → closed (via CLOSE)
// ... and more
```
Simple paths provide complete transition coverage - every valid sequence through the machine.
## `getPathsFromEvents(logic, events, options?)` [#getpathsfromeventslogic-events-options]
Traces a specific sequence of events and returns the resulting path. Useful for validating that a specific user flow works as expected.
```ts
import { getPathsFromEvents } from 'xstate/graph';
const path = getPathsFromEvents(feedbackMachine, [
{ type: 'CLICK_BAD' },
{ type: 'SUBMIT' },
{ type: 'CLOSE' }
]);
// Returns:
// {
// state: { value: 'closed' },
// ,
// steps: [
// { state: { value: 'question' }, event: { type: 'CLICK_BAD' } },
// { state: { value: 'form' }, event: { type: 'SUBMIT' } },
// { state: { value: 'thanks' }, event: { type: 'CLOSE' } }
// ]
// }
```
## Traversal options [#traversal-options]
All path functions accept an options object to customize traversal:
### `events` [#events]
Specify event payloads for events that require data. By default, events are traversed with just their type.
```ts
import { setup, assign } from 'xstate';
import { getShortestPaths } from 'xstate/graph';
const counterMachine = setup({
types: {
events: {} as { type: 'INC'; value: number }
}
}).createMachine({
id: 'counter',
initial: 'active',
context: { count: 0 },
states: {
active: {
on: {
INC: {
actions: assign({
count: ({ context, event }) => context.count + event.value
})
}
}
}
}
});
const paths = getShortestPaths(counterMachine, {
events: [
{ type: 'INC', value: 1 },
{ type: 'INC', value: 5 },
{ type: 'INC', value: 10 }
]
});
```
You can also provide a function that returns events based on the current state:
```ts
const paths = getShortestPaths(counterMachine, {
events: (state) => {
// Generate different events based on context
if (state.context.count < 10) {
return [{ type: 'INC', value: 1 }];
}
return [{ type: 'INC', value: 10 }];
}
});
```
### `toState` [#tostate]
Filter paths to only those reaching states matching a condition:
```ts
const paths = getShortestPaths(feedbackMachine, {
toState: (state) => state.value === 'closed'
});
// Only returns paths ending in 'closed' state
```
### `fromState` [#fromstate]
Start traversal from a specific state instead of the initial state:
```ts
import { createActor } from 'xstate';
const actor = createActor(feedbackMachine).start();
actor.send({ type: 'CLICK_BAD' });
const paths = getShortestPaths(feedbackMachine, {
fromState: actor.getSnapshot()
});
// Paths starting from 'form' state
```
### `stopWhen` [#stopwhen]
Stop traversing when a condition is met:
```ts
const paths = getShortestPaths(counterMachine, {
events: [{ type: 'INC', value: 1 }],
stopWhen: (state) => state.context.count >= 5
});
// Stops exploring paths once count reaches 5
```
### `limit` [#limit]
Maximum number of states to traverse (prevents infinite loops with context):
```ts
const paths = getShortestPaths(counterMachine, {
events: [{ type: 'INC', value: 1 }],
limit: 100 // Stop after 100 unique states
});
```
### `serializeState` and `serializeEvent` [#serializestate-and-serializeevent]
Customize how states and events are serialized for comparison. By default, states are serialized as JSON strings of their value and context.
```ts
const paths = getShortestPaths(machine, {
serializeState: (state) => {
// Only consider state value, ignore context
return JSON.stringify(state.value);
},
serializeEvent: (event) => {
// Custom event serialization
return event.type;
}
});
```
## Working with context [#working-with-context]
When machines have dynamic context, the state space can become infinite. Use `stopWhen` or `limit` to bound the traversal:
```ts
import { setup, assign } from 'xstate';
import { getShortestPaths } from 'xstate/graph';
const counterMachine = setup({
types: {
events: {} as { type: 'INC'; value: number } | { type: 'DEC'; value: number }
}
}).createMachine({
id: 'counter',
initial: 'counting',
context: { count: 0 },
states: {
counting: {
always: {
target: 'done',
guard: ({ context }) => context.count >= 10
},
on: {
INC: {
actions: assign({
count: ({ context, event }) => context.count + event.value
})
},
DEC: {
actions: assign({
count: ({ context, event }) => context.count - event.value
})
}
}
},
done: {
type: 'final'
}
}
});
const paths = getShortestPaths(counterMachine, {
events: [
{ type: 'INC', value: 1 },
{ type: 'INC', value: 5 },
{ type: 'DEC', value: 1 }
],
// Bound the state space
stopWhen: (state) => state.context.count > 15 || state.context.count < -5
});
```
## `getAdjacencyMap(logic, options?)` [#getadjacencymaplogic-options]
Returns a map representing the state machine as a graph, with states as keys and their transitions as values.
```ts
import { getAdjacencyMap } from 'xstate/graph';
const adjacencyMap = getAdjacencyMap(feedbackMachine);
// Structure:
// {
// '"question"': {
// state: { value: 'question', ... },
// transitions: {
// '{"type":"CLICK_GOOD"}': { event: {...}, state: {...} },
// '{"type":"CLICK_BAD"}': { event: {...}, state: {...} },
// '{"type":"CLOSE"}': { event: {...}, state: {...} }
// }
// },
// '"form"': { ... },
// ...
// }
```
## `toDirectedGraph(machine)` [#todirectedgraphmachine]
Converts a machine to a directed graph structure for visualization:
```ts
import { toDirectedGraph } from 'xstate/graph';
const digraph = toDirectedGraph(feedbackMachine);
// Structure:
// {
// id: 'feedback',
// stateNode: StateNode,
// children: [
// { id: 'feedback.question', children: [], edges: [...] },
// { id: 'feedback.form', children: [], edges: [...] },
// ...
// ],
// edges: [
// { source: StateNode, target: StateNode, transition: {...} },
// ...
// ]
// }
```
## Model-based testing [#model-based-testing]
Path generation enables model-based testing - generating test cases directly from your state machine. Use `createTestModel` to wrap your machine with testing utilities:
```ts
import { createMachine } from 'xstate';
import { createTestModel } from 'xstate/graph';
const toggleMachine = createMachine({
id: 'toggle',
initial: 'inactive',
states: {
inactive: {
on: { TOGGLE: 'active' }
},
active: {
on: { TOGGLE: 'inactive' }
}
}
});
const model = createTestModel(toggleMachine);
// Get paths for testing
const paths = model.getShortestPaths();
// Use with your test framework
describe('toggle', () => {
for (const path of paths) {
it(`reaches ${JSON.stringify(path.state.value)}`, async () => {
await path.test({
events: {
TOGGLE: async () => {
// Execute the toggle action in your app
await page.click('#toggle-button');
}
},
states: {
inactive: async (state) => {
// Assert the app is in inactive state
await expect(page.locator('#status')).toHaveText('Inactive');
},
active: async (state) => {
await expect(page.locator('#status')).toHaveText('Active');
}
}
});
});
}
});
```
### TestModel methods [#testmodel-methods]
* `model.getShortestPaths(options?)` - get shortest paths
* `model.getSimplePaths(options?)` - get all simple paths
* `model.getPaths(pathGenerator)` - use custom path generator
### Path testing [#path-testing]
Each path returned by `TestModel` has a `test` method that:
1. Starts from the initial state
2. Executes each event in the path using your event handlers
3. Verifies each state using your state assertions
```ts
path.test({
events: {
// Map event types to async functions that execute the event
CLICK_GOOD: async () => await page.click('.good-button'),
SUBMIT: async () => await page.click('button[type="submit"]')
},
states: {
// Map state values to async assertions
question: async () => await expect(page.locator('.question')).toBeVisible(),
form: async () => await expect(page.locator('form')).toBeVisible(),
thanks: async () => await expect(page.locator('.thanks')).toBeVisible()
}
});
```
You can [generate test paths from your state machines in Stately Studio](generate-test-paths.mdx), with support for Playwright, Vitest, and custom formats.
## Path deduplication [#path-deduplication]
When using simple paths, you may get many paths where shorter paths are prefixes of longer ones. The `deduplicatePaths` utility removes redundant paths:
```ts
import { getSimplePaths, deduplicatePaths } from 'xstate/graph';
const allPaths = getSimplePaths(machine);
const uniquePaths = deduplicatePaths(allPaths);
// Removes paths that are prefixes of longer paths
// e.g., [A→B] is removed if [A→B→C] exists
```
## Example: Complete test generation [#example-complete-test-generation]
```ts
import { createMachine } from 'xstate';
import { createTestModel } from 'xstate/graph';
import { test, expect } from 'vitest';
const authMachine = createMachine({
id: 'auth',
initial: 'loggedOut',
states: {
loggedOut: {
on: {
LOGIN: 'loggingIn'
}
},
loggingIn: {
on: {
SUCCESS: 'loggedIn',
FAILURE: 'loggedOut'
}
},
loggedIn: {
on: {
LOGOUT: 'loggedOut'
}
}
}
});
const model = createTestModel(authMachine);
describe('auth flows', () => {
const paths = model.getShortestPaths({
toState: (state) => state.matches('loggedIn')
});
for (const path of paths) {
test(path.description, async () => {
// Setup
const app = await setupApp();
await path.test({
events: {
LOGIN: async () => {
await app.fillLoginForm('user', 'pass');
await app.submit();
},
SUCCESS: async () => {
await app.mockAuthSuccess();
},
LOGOUT: async () => {
await app.clickLogout();
}
},
states: {
loggedOut: async () => {
expect(app.isLoggedIn()).toBe(false);
},
loggingIn: async () => {
expect(app.isLoading()).toBe(true);
},
loggedIn: async () => {
expect(app.isLoggedIn()).toBe(true);
}
}
});
});
}
});
```
# Guards (/docs/guards)
A **guard** is a condition function that the machine checks when it goes through an event. If the condition is `true`, the machine follows the transition to the next state. If the condition is `false`, the machine follows the rest of the conditions to the next state.
A **guarded transition** is a transition that is enabled only if its `guard` evaluates to `true`. The guard determines whether or not the transition can be enabled. Any transition can be a guarded transition.
You can easily visualize and simulate guarded transitions in Stately’s editor. [Read more about guards in Stately’s editor](/docs/editor-states-and-transitions/#add-guards).
Guards should be pure, synchronous functions that return either `true` or `false`.
```ts
import { createMachine } from 'xstate';
const feedbackMachine = createMachine(
{
// ...
states: {
form: {
on: {
'feedback.submit': {
// [!code highlight:1]
guard: 'isValid',
target: 'submitting',
},
},
},
submitting: {
// ...
},
},
},
{
// [!code highlight:5]
guards: {
isValid: ({ context }) => {
return context.feedback.length > 0;
},
},
},
);
```
**XState v5 requires TypeScript version 5.0 or greater.**
For best results, use the latest TypeScript version. [Read more about XState and TypeScript](typescript)
You can strongly type the `guards` of your machine by setting up their implementations in `setup({ guards: { … } })`. You can provide the `params` type in the 2nd argument of the guard function:
```ts
import { setup } from 'xstate';
const machine = setup({
// [!code highlight:5]
guards: {
isGreaterThan: (_, params: { count: number; min: number }) => {
return params.count > params.min;
},
},
}).createMachine({
// ...
on: {
someEvent: {
guard: {
type: 'isGreaterThan',
// Strongly-typed params
params: ({ event }) => ({
count: event.count,
min: 10,
}),
},
// ...
},
},
});
```
## Guards cheatsheet [#guards-cheatsheet]
```ts
import { createMachine } from 'xstate';
const feedbackMachine = createMachine(
{
// ...
states: {
form: {
on: {
'feedback.submit': {
// [!code highlight:1]
guard: 'isValid',
target: 'submitting',
},
},
},
submitting: {
// ...
},
},
},
{
// [!code highlight:5]
guards: {
isValid: ({ context }) => {
return context.feedback.length > 0;
},
},
},
);
```
### Cheatsheet: multiple guarded transitions [#cheatsheet-multiple-guarded-transitions]
```ts
import { createMachine } from 'xstate';
const feedbackMachine = createMachine({
// ...
prompt: {
on: {
// [!code highlight:15]
'feedback.provide': [
// Taken if 'sentimentGood' guard evaluates to `true`
{
guard: 'sentimentGood',
target: 'thanks',
},
// Taken if none of the above guarded transitions are taken
// and if 'sentimentBad' guard evaluates to `true`
{
guard: 'sentimentBad',
target: 'form',
},
// Default transition
{ target: 'form' },
],
},
},
});
```
### Cheatsheet: Higher-level guards [#cheatsheet-higher-level-guards]
```ts
import { createMachine, and } from 'xstate';
const loginMachine = createMachine({
on: {
event: {
guard: and(['isValid', 'isAuthorized']);
}
}
});
```
### Cheatsheet: Combined higher-level guards [#cheatsheet-combined-higher-level-guards]
```ts
import { createMachine, and, or } from 'xstate';
const loginMachine = createMachine({
on: {
event: {
guard: and(['isValid', or(['isAuthorized', 'isGuest'])]);
}
}
});
```
# History states (/docs/history-states)
A history state is a special type of state (a *pseudostate*) that remembers the last [child state](parent-states) that was active before its parent state is exited. When a transition from outside the parent state targets a history state, the remembered child state is entered.
This allows machines to "remember" where they left off when exiting and reentering a parent state.
* If no child state remembered, history goes to `.target` state, if it is specified
* Otherwise, go to [initial state](initial-states)
A history state returns the parent state to its most recently active child state. The box with an **H** inside represents the history state.
The history state can be deep or shallow:
* A shallow history state remembers the immediate child’s state.
* A deep history state remembers the deepest active state or states inside its child states.
```ts
import { createMachine } from 'xstate';
const checkoutMachine = createMachine({
// ...
states: {
payment: {
initial: 'card',
states: {
card: {},
paypal: {},
// [!code highlight:1]
hist: { type: 'history' },
},
},
address: {
on: {
back: {
target: 'payment.hist',
},
},
},
},
});
```
## Shallow vs. deep history [#shallow-vs-deep-history]
* Shallow history states only remember the last active direct child state.
* Deep history states remember all active descendant states.
## History target [#history-target]
* Normally, history states target the most recent child state of its parent state
* If the history state is entered but the parent state was never visited, the parent's initial state is entered.
* However, you can add a `target: 'childKey'` to specify the default child state that should be entered
## History states cheatsheet [#history-states-cheatsheet]
### Cheatsheet: create a history state (shallow by default) [#cheatsheet-create-a-history-state-shallow-by-default]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
// ...
states: {
hist: { type: 'history' },
firstState: {},
someState: {},
anotherState: {},
},
});
```
### Cheatsheet: create a deep history state [#cheatsheet-create-a-deep-history-state]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
// ...
states: {
hist: {
type: 'history',
history: 'deep',
},
firstState: {},
someState: {},
anotherState: {},
},
});
```
### Cheatsheet: create a history state with a target [#cheatsheet-create-a-history-state-with-a-target]
```ts
import { createMachine } from 'xstate';
const machine = createMachine({
// ...
initialState: 'firstState',
states: {
hist: {
type: 'history',
target: 'someState',
},
firstState: {},
someState: {},
anotherState: {},
},
});
```
# Share machine images using their image URL (/docs/image)
You can share an image of your machine anywhere that supports images. You can use the image URL for live-updating images where the machine is always updated with your latest changes. Machine images can be helpful in documentation, including GitHub pull requests.
The machine below demonstrates the copy image URL flow.
You can also [embed your machine](embed) for a focused non-editable view of your machine in Stately Studio’s editor.
## Copy the image URL [#copy-the-image-url]
Use the 
```
# Usage with Immer (/docs/immer)
[Immer](https://immerjs.github.io/immer/) is a library that makes it more convenient to work with updating data immutably. It can be used with XState to immutably update `context` in assignments.
It is recommended to use Immer directly with XState instead of the `@xstate/immer` package, which is deprecated.
## Installation [#installation]
Install the latest versions of `xstate` and `immer` from npm:
```bash
npm install xstate immer
```
```bash
pnpm install xstate immer
```
```bash
yarn add xstate immer
```
See [the Immer installation docs](https://immerjs.github.io/immer/installation) for more information.
## Immer usage [#immer-usage]
XState already allows you to immutably update `context` partially or completely in [assign actions](/docs/actions#assign-action). However, for more complex scenarios, you may want to use Immer to update `context` in a less verbose way.
```ts
import { createMachine, assign } from 'xstate';
// [!code highlight:1]
import { produce } from 'immer';
const machine = createMachine({
id: 'todos',
context: {
todos: [],
filter: 'all',
},
// ...
on: {
'todo.complete': {
// [!code highlight:8]
// Using Immer to update a single context property
actions: assign({
todos: ({ context, event }) =>
produce(context.todos, (draftTodos) => {
const todo = draftTodos.find((t) => t.id === event.todo.id);
todo.completed = true;
}),
}),
},
'todos.add': {
// [!code highlight:14]
// Using Immer to update multiple context properties
actions: assign(({ context, event }) =>
produce(context, (draftContext) => {
draftContext.todos.push({
id: event.todo.id,
description: event.todo.description,
completed: false,
});
if (draftContext.filter === 'all') {
draftContext.filter = 'active';
}
}),
),
},
},
});
```
# Import from code (/docs/import-from-code)
Importing from code is helpful if you’ve already built machines while working with [XState](xstate), or have created a machine using our older [Stately Viz](https://stately.ai/viz) but haven’t yet tried Stately Studio’s editor.
Watch our [“Import from code” video on YouTube](https://www.youtube.com/watch?v=DAoIFaugDLo) (2m24s).
## Import state machines [#import-state-machines]
Your state machine code should be formatted as a [`createMachine()` factory function](/docs/actors#createmachine) before import. The importer has basic validation in case your machine has basic errors, including reminding you if the `createMachine` definition is missing.
[Check out an importable machine code example at the end of this page](#machine-code-example).
**Caution**: importing code will overwrite your current or selected machine unless you create a new machine from the machines list inside a project.
The Stately editor now supports importing multiple machines from code.
### Create a new machine inside a project using imported code [#create-a-new-machine-inside-a-project-using-imported-code]
Create a
Connect GitHub repo is a premium feature of Stately Studio. [Check out the features on our Pro plan](studio-pro-plan), [Team plan](studio-team-plan), [Enterprise plan](studio-enterprise-plan) or [upgrade your existing plan](https://stately.ai/registry/billing).
While this feature is in beta, it works best when connecting less than 100
files. For larger repos, we recommend creating single-file PRs. Read about
that feature
[here](../../blog/2024-02-16-changelog#make-github-pull-requests-for-single-files-from-inside-stately-studio).
## Connect GitHub repo [#connect-github-repo]
Use the **Connect GitHub repo** button found in the Projects dashboard to start connecting a GitHub repo. There are three steps to setting up your GitHub repo as a connected project:
1. Select the repo. You can choose the repos based on your GitHub permissions.
2. Select the branch. You can choose any branch in your repo.
3. Choose the files you want to sync. You can sync any JavaScript or TypeScript files, but only XState machines will be imported.
Choose the XState version for your synced machines from the dropdown menu in the
### Auto-sync [#auto-sync]
Enabling **auto-sync** will automatically fetch the latest changes from your connected repository every time you open or refresh the project in the Studio.
Disable auto-sync from the GitHub options from the
Read more in [our blog post about importing a machine from a GitHub URL](https://stately.ai/blog/2023-02-06-github-import-machines).
# Stately & XState docs (/docs)
## Welcome to the Stately and XState docs [#welcome-to-the-stately-and-xstate-docs]
[Stately.ai](studio) is a visual software modeling platform for modeling your app & business logic as state machines/statecharts and actors, and scales to any level of complexity.
XState is a best-in-class open source library for
orchestrating and managing complex application logic in JavaScript and TypeScript apps.
These docs are for XState v5. Looking for XState v4 docs? [Find them here](https://xstate.js.org/docs/). We recommend [migrating to v5](/docs/migration).
## Quick start [#quick-start]
Install XState:
```bash
npm install xstate
```
Create a state machine:
```ts
import { createMachine, createActor } from 'xstate';
const toggleMachine = createMachine({
id: 'toggle',
initial: 'inactive',
states: {
inactive: { on: { toggle: 'active' } },
active: { on: { toggle: 'inactive' } },
},
});
const toggleActor = createActor(toggleMachine);
toggleActor.start();
toggleActor.send({ type: 'toggle' });
console.log(toggleActor.getSnapshot().value); // 'active'
toggleActor.send({ type: 'toggle' });
console.log(toggleActor.getSnapshot().value); // 'inactive'
```
[Read the full quick start guide](/docs/quick-start) to learn more.
Jump straight into learning how to use Stately Studio editor, starting
with states.
Find out more about Stately Studio's visual editor and collaborating
with your team using Stately Studio's premium features.
With our no-code introduction.
Get started with our JavaScript and TypeScript library for state
machines and statecharts.
We're [Stately](https://stately.ai), a small team founded by [David Khourshid](https://twitter.com/davidkpiano), the creator of XState. Stately is building Stately Studio, where you can visualize your application logic and collaborate with your whole team.
# Initial states (/docs/initial-states)
When a state machine starts, it enters the **initial state** first. A machine can only have one top-level initial state; if there were multiple initial states, the machine wouldn’t know where to start!
In XState, the initial state is defined by the `initial` property on the machine config:
```ts
const feedbackMachine = createMachine({
id: 'feedback',
// [!code highlight:2]
// Initial state
initial: 'prompt',
// Finite states
states: {
// [!code highlight:1]
prompt: {
/* ... */
},
// ...
},
});
```
In our video player, paused is the initial state because the video player is paused by default and requires user interaction to start playing.
Watch our [“What are initial states?” video on YouTube](https://www.youtube.com/watch?v=goCpmgyrjL0\&list=PLvWgkXBB3dd4I_l-djWVU2UGPyBgKfnTQ\&index=3) (1m17s).
Input is coming to Stately Studio’s editor soon.
## Creating actors with input [#creating-actors-with-input]
You can pass `input` to any kind of actor by reading this input from the `input` property of the first argument to actor logic creators, such as `fromPromise()`, `fromTransition()`, `fromObservable()`, and other actor logic creators.
**Input with `fromPromise()`:**
```ts
import { createActor, fromPromise } from 'xstate';
const userFetcher = fromPromise(({ input }: { input: { userId: string } }) => {
return fetch(`/users/${input.userId}`).then((res) => res.json());
});
const userFetcherActor = createActor(userFetcher, {
// [!code highlight:3]
input: {
userId: '123',
},
}).start();
userFetcherActor.onDone((data) => {
console.log(data);
// logs the user data for userId 123
});
```
**Input with `fromTransition()`:**
```ts
import { createActor, fromTransition } from 'xstate';
const counter = fromTransition((state, event)) => {
if (event.type === 'INCREMENT') {
return { count: state.count + 1 };
}
return state;
}, ({ input }: { input: { startingCount?: number } }) => ({
count: input.startingCount ?? 0,
});
const counterActor = createActor(counter, {
// [!code highlight:23]
input: {
startingCount: 10,
}
});
```
**Input with `fromObservable()`:**
```ts
import { createActor, fromObservable } from 'xstate';
import { interval } from 'rxjs';
const intervalLogic = fromObservable(
({ input }: { input: { interval: number } }) => {
return interval(input.interval);
},
);
const intervalActor = createActor(intervalLogic, {
// highlight-start
input: {
interval: 1000,
},
});
intervalActor.start();
```
## Initial event input [#initial-event-input]
When an actor is started, it will automatically send a special event named `xstate.init` to itself. If `input` is provided to the `createActor(logic, { input })` function, it will be included in the `xstate.init` event:
```ts
import { createActor, createMachine } from 'xstate';
const feedbackMachine = createMachine({
// [!code highlight:4]
entry: ({ event }) => {
console.log(event.input);
// logs { userId: '123', defaultRating: 5 }
},
// ...
});
const feedbackActor = createActor(feedbackMachine, {
input: {
userId: '123',
defaultRating: 5,
},
}).start();
```
## Invoking actors with input [#invoking-actors-with-input]
You can provide input to invoked actors via the `input` property of the `invoke` configuration:
```ts
import { createActor, setup } from 'xstate';
const feedbackMachine = setup({
actors: {
liveFeedback: fromPromise(({ input }: { input: { domain: string } }) => {
return fetch(`https://${input.domain}/feedback`).then((res) =>
res.json(),
);
}),
},
}).createMachine({
invoke: {
src: 'liveFeedback',
// [!code highlight:3]
input: {
domain: 'stately.ai',
},
},
});
```
The `invoke.input` property can be a static input value or a function that returns the input value. The function will be called with an object that contains the current `context` and `event`:
```ts
import { createActor, setup } from 'xstate';
const feedbackMachine = setup({
actors: {
// [!code highlight:3]
fetchUser: fromPromise(({ input }) => {
return fetch(`/users/${input.userId}`).then((res) => res.json());
}),
},
}).createMachine({
context: {
userId: '',
feedback: '',
rating: 0,
},
invoke: {
src: 'fetchUser',
// [!code highlight:1]
input: ({ context }) => ({ userId: context.userId }),
},
// ...
});
```
## Spawning actors with input [#spawning-actors-with-input]
You can provide input to spawned actors via the `input` property of the `spawn` configuration:
```ts
import { createActor, setup, type AnyActorRef } from 'xstate';
const feedbackMachine = setup({
types: {
context: {} as {
userId: string;
feedback: string;
rating: number;
emailRef: AnyActorRef;
},
},
actors: {
// [!code highlight:6]
emailUser: fromPromise(({ input }: { input: { userId: string } }) => {
return fetch(`/users/${input.userId}`, {
method: 'POST',
// ...
});
}),
},
}).createMachine({
context: {
userId: '',
feedback: '',
rating: 0,
emailRef: null,
},
// ...
on: {
'feedback.submit': {
actions: assign({
emailRef: ({ context, spawn }) => {
return spawn('emailUser', {
// [!code highlight:1]
input: { userId: context.userId },
});
},
}),
},
},
// ...
});
```
## Use-cases [#use-cases]
Input is useful for creating reusable machines that can be configured with different input values.
* Replaces the old way of writing a factory function for machines:
```ts
// Old way: using a factory function
const createFeedbackMachine = (userId, defaultRating) => {
return createMachine({
context: {
userId,
feedback: '',
rating: defaultRating,
},
// ...
});
};
const feedbackMachine1 = createFeedbackMachine('123', 5);
const feedbackActor1 = createActor(feedbackMachine1).start();
// New way: using input
const feedbackMachine = createMachine({
context: ({ input }) => ({
userId: input.userId,
feedback: '',
rating: input.defaultRating,
}),
// ...
});
const feedbackActor = createActor(feedbackMachine, {
input: {
userId: '123',
defaultRating: 5,
},
});
```
### Passing new data to an actor [#passing-new-data-to-an-actor]
Changing the input will not cause the actor to be restarted. You need to send an event to the actor to pass the new data to the actor:
```tsx
const Component = (props) => {
const feedbackActor = useActor(feedbackMachine, {
input: {
userId: props.userId,
defaultRating: props.defaultRating,
},
});
useEffect(() => {
feedbackActor.send({
type: 'userId.change',
userId: props.userId,
});
}, [props.userId]);
// ...
};
```
## Input and TypeScript [#input-and-typescript]
**XState v5 requires TypeScript version 5.0 or greater.**
For best results, use the latest TypeScript version. [Read more about XState and TypeScript](typescript)
You can strongly type the `input` of your machine in the `types.input` property of the machine setup.
```ts
import { createActor, setup } from 'xstate';
const machine = setup({
types: {
// [!code highlight:4]
input: {} as {
userId: string;
defaultRating: number;
};
context: {} as {
userId: string;
feedback: string;
rating: number;
};
},
}).createMachine({
context: ({ input }) => ({
userId: input.userId,
feedback: '',
rating: input.defaultRating,
}),
});
const actor = createActor(machine, {
input: {
userId: '123',
defaultRating: 5,
},
});
```
## Input cheatsheet [#input-cheatsheet]
Use our XState input cheatsheet below to get started quickly.
### Cheatsheet: providing input [#cheatsheet-providing-input]
```ts
const feedbackActor = createActor(feedbackMachine, {
input: {
userId: '123',
defaultRating: 5,
},
});
```
### Cheatsheet: providing input to invoked actors [#cheatsheet-providing-input-to-invoked-actors]
```ts
const feedbackMachine = createMachine({
invoke: {
src: 'liveFeedback',
input: {
domain: 'stately.ai',
},
},
});
```
### Cheatsheet: providing dynamic input to invoked actors [#cheatsheet-providing-dynamic-input-to-invoked-actors]
```ts
const feedbackMachine = createMachine({
context: {
userId: 'some-user-id',
},
invoke: {
src: 'fetchUser',
input: ({ context }) => ({ userId: context.userId }),
},
});
```
### Cheatsheet: providing dynamic input from event properties to invoked actors [#cheatsheet-providing-dynamic-input-from-event-properties-to-invoked-actors]
```ts
const feedbackMachine = createMachine({
types: {
events:
| { type: 'messageSent', message: string }
| { type: 'incremented', count: number },
},
invoke: {
src: 'fetchUser',
input: ({ event }) => {
// [!code highlight:1]
assertEvent(event, 'messageSent');
return {
message: event.message,
};
},
},
});
```
### Cheatsheet: providing input to spawned actors [#cheatsheet-providing-input-to-spawned-actors]
```ts
const feedbackMachine = createMachine({
context: {
userId: '',
},
// ...
on: {
'feedback.submit': {
actions: assign({
emailRef: ({ context, spawn }) => {
return spawn('emailUser', {
input: { userId: context.userId },
});
},
}),
},
},
// ...
});
```
# Inspection (/docs/inspection)
The Inspect API is a way to inspect the state transitions of your state machines and every aspect of actors in an actor system. Including:
* Actor lifecycle
* Actor event communication
* Actor snapshot updates
* State transition microsteps
[We’ve recently released Stately Inspector](../../blog/2024-01-15-stately-inspector/), a universal tool that enables you to visually inspect the state of any application, frontend or backend, with the visualization of Stately’s editor.
[Learn more about Stately Inspector](inspector)
The Inspect API lets you attach an “inspector,” an observer that observes inspection events, to the root of an actor system:
```tsx
const actor = createActor(machine, {
inspect: (inspectionEvent) => {
// type: '@xstate.actor' or
// type: '@xstate.snapshot' or
// type: '@xstate.event' or
// type: '@xstate.microstep'
console.log(inspectionEvent);
},
});
```
The inspector will receive inspection events for every actor in the system, giving you granular visibility into everything happening, from how an individual actor is changing to how actors communicate with each other.
## Inspection events [#inspection-events]
Inspection events are event objects that have a `type` property that indicates the type of inspection event. There are four types of inspection events:
* `@xstate.actor` for [Actor inspection events](#actor-inspection-events)
* `@xstate.event` for [Event inspection events](#event-inspection-events)
* `@xstate.snapshot` for [Snapshot inspection events](#snapshot-inspection-events)
* `@xstate.microstep` for [Microstep inspection events](#microstep-inspection-events)
## Actor inspection events [#actor-inspection-events]
The actor inspection event (`@xstate.actor`) is emitted when an actor in the system is created. It contains the following properties:
* `type` - the type of inspection event, always `'@xstate.actor'`
* `actorRef` - the reference to the actor
* `rootId` - the session ID of the root actor of the system
Example of an actor inspection event:
```js
{
type: '@xstate.actor',
actorRef: {/* Actor reference */},
rootId: 'x:0',
}
```
## Event inspection events [#event-inspection-events]
The event inspection event (`@xstate.event`) is emitted when an event is sent to an actor. It contains the following properties:
* `type` - the type of inspection event, always `'@xstate.event'`
* `actorRef` - the reference to the target actor of the event
* `rootId` - the session ID of the root actor of the system
* `event` - the event object that was sent
* `sourceRef` - the reference to the source actor that sent the event, or `undefined` if the source is not known or an event was sent directly to the actor
Example of an event inspection event:
```js
{
type: '@xstate.event',
actorRef: {/* Actor reference */},
rootId: 'x:0',
event: {
type: 'someEvent',
message: 'hello'
},
sourceRef: {/* Actor reference */},
}
```
## Snapshot inspection events [#snapshot-inspection-events]
The snapshot inspection event (`@xstate.snapshot`) is emitted when an actor's snapshot is updated. It contains the following properties:
* `type` - the type of inspection event, always `'@xstate.snapshot'`
* `actorRef` - the reference to the actor
* `rootId` - the session ID of the root actor of the system
* `snapshot` - the most recent snapshot of the actor
* `event` - the event that caused the snapshot to be updated
Example of a snapshot inspection event:
```js
{
type: '@xstate.snapshot',
actorRef: {/* Actor reference */},
rootId: 'x:0',
snapshot: {
status: 'active',
context: { count: 31 },
// ...
},
event: {
type: 'increment'
}
}
```
## Microstep inspection events [#microstep-inspection-events]
The microstep inspection event (`@xstate.microstep`) is emitted for each individual state transition, including intermediate "microsteps", that occurs during the processing of an event. This is particularly useful for observing eventless transitions (like `always` transitions) and understanding the step-by-step progression through multiple states.
**Observing transient states:** Subscribers to an actor only receive the *final* snapshot after all transitions (including eventless ones) are applied. So states that are only entered and left via `always` transitions in the same step never appear in `subscribe()`, `waitFor()`, or when using `snapshot.matches()` / `snapshot.hasTag()`. To observe those intermediate states, use the `@xstate.microstep` inspection event. For more detail and alternatives (such as `after: { 0: '...' }` when you need observability), see [Eventless (always) transitions – Observability and transient states](eventless-transitions#observability-and-transient-states).
It contains the following properties:
* `type: '@xstate.microstep'`
* `value` - the current state value after this microstep
* `event` - the event that triggered this microstep
* `transitions` - an array of transition objects that occurred in this microstep
Each transition object in the `transitions` array contains:
* `eventType` - the event type that triggered the transition (empty string for eventless transitions)
* `target` - an array of target state paths
Example of a microstep inspection event:
```json5
{
type: '@xstate.microstep',
value: 'c',
event: {
type: 'EV',
},
transitions: [
{
eventType: 'EV',
target: ['(machine).b'],
},
{
eventType: '',
target: ['(machine).c'],
},
],
}
```
Example of microstep events
Here's an example of microstep events:
```tsx
const machine = createMachine({
initial: 'a',
states: {
a: {
on: {
EV: 'b',
},
},
b: {
always: 'c', // This will trigger automatically after entering state 'b'
},
c: {},
},
});
const events = [];
const actorRef = createActor(machine, {
inspect: (ev) => events.push(ev),
}).start();
actorRef.send({ type: 'EV' });
```
The microstep events will look like this:
```json5
// First microstep: EV transition to state 'b'
{
type: '@xstate.microstep',
value: 'b',
event: {
type: 'EV'
},
transitions: [
{
eventType: 'EV',
target: ['(machine).b']
}
]
},
// Second microstep: always transition to state 'c'
{
type: '@xstate.microstep',
value: 'c',
event: {
type: 'EV'
},
transitions: [
{
eventType: '', // Empty string indicates eventless transition
target: ['(machine).c']
}
]
}
```
# Inspector (/docs/inspector)
# Stately Inspector [#stately-inspector]
Stately Inspector is a tool that allows you to inspect your application’s state visually. It primarily works with frontend applications using XState but can also work with backend code and code that uses any state management solution.
[Read about our recent release of Stately Inspector on our blog](../blog/2024-01-15-introducing-stately-inspector/).
## Install Stately Inspector [#install-stately-inspector]
To inspect applications with Stately Inspector, install [Stately Inspect](https://github.com/statelyai/inspect) from npm via `@statelyai/inspect`:
```bash
npm install @statelyai/inspect
```
Then import the relevant inspector creator into your app. The creator is used to create an inspector (e.g., a browser or WebSocket inspector) that you can use to either connect to XState actors and/or manually send inspection events to Stately Inspector:
```ts
import { createActor } from 'xstate';
// [!code highlight:1]
import { createBrowserInspector } from '@statelyai/inspect';
import { machine } from './machine';
// [!code highlight:1]
const { inspect } = createBrowserInspector();
// ...
const actor = createActor(machine, {
// [!code highlight:1]
inspect,
// ... other actor options
});
actor.start();
```
When you run your app, a new tab or popup window will open with the Inspector.
When using the browser inspector, ensure that the popup window is not blocked by your browser’s popup blocker.
## Inspector options [#inspector-options]
You can pass the following options to the browser inspector:
* `filter` - a function that takes an inspection event and returns `true` if the event should be sent to the Stately Inspector.
* `serialize` - a function that takes an inspection event and allows you to serialize it before sending it to the Stately Inspector.
* `autoStart` - whether to automatically start the inspector. Defaults to `true`.
* If `autoStart: false`, you can start the inspector by calling `inspector.start()`.
* `url` - the URL of the Stately Inspector to open. Defaults to `https://stately.ai/inspector`.
* `iframe` - the `