Skip to content
Version: XState v5

Quick start

This quick start guide will help you get started with XState and Stately Studio. You will learn how to create a state machine, create an actor from that state machine, send events to that actor, and observe the state changes.

Installing XState V5 beta​

XState is a visual state management and orchestration library for JavaScript and TypeScript.

Install the XState V5 beta using your preferred package manager:

npm install xstate@beta

Create a machine​

In XState, a machine is an object that contains all the logic for an actor. In this example, we will create a simple toggle machine that can be in one of two states: Active or Inactive. The toggle event will toggle the state between Active and Inactive.

import { createMachine } from 'xstate';

const toggleMachine = createMachine({
id: 'toggle',
initial: 'Inactive',
states: {
Inactive: {
on: { toggle: 'Active' },
},
Active: {
on: { toggle: 'Inactive' },
},
},
});

Read our introduction to state machines and statecharts to familiarize yourself with the concepts.

Create an actor and send events​

Machine logic can be used to create an actor. An actor is a running process that can receive messages (events), send messages and change its behavior based on the messages it receives.

import { createMachine, createActor } from 'xstate';

const toggleMachine = createMachine({
// Machine code from above
});

// Create an actor that you can send events to.
// Note: the actor is not started yet!
const actor = createActor(machine);

// Subscribe to snapshots (emitted state changes) from the actor
actor.subscribe((snapshot) => {
console.log('Value:', snapshot.value);
});

// Start the actor
actor.start(); // logs 'Inactive'

// Send events
actor.send({ type: 'toggle' }); // logs 'Active'
actor.send({ type: 'toggle' }); // logs 'Inactive'

Use delayed transitions​

Delayed transitions are transitions that automatically happen after a specified interval of time.

export const toggleMachine = createMachine({
id: 'toggle',
initial: 'Inactive',
states: {
Inactive: {
on: { toggle: 'Active' },
},
Active: {
on: { toggle: 'Inactive' },
after: { 2000: 'Inactive' },
},
},
});

Handle context data​

Context is how you store data in a state machine actor.

import { assign, createMachine } from 'xstate';

export const toggleMachine = createMachine({
id: 'toggle',
context: { count: 0 },
initial: 'Inactive',
states: {
Inactive: {
on: { toggle: 'Active' },
},
Active: {
entry: assign({
count: ({ context }) => context.count + 1
}),
on: { toggle: 'Inactive' },
after: { 2000: 'Inactive' },
},
},
});

Use your machine with a framework​

import { useMachine } from '@xstate/react';
import { toggleMachine } from './toggleMachine';

const App = () => {
const [state, send] = useMachine(toggleMachine);

return (
<div>
<div>Value: {state.value}</div>
<button onClick={() => send({ type: 'toggle' })}>
Toggle
</button>
</div>
);
};