Skip to content

What is a statechart?

Install XState and create a statechart by importing createMachine from xstate.

ts
import { createMachine } from 'xstate';
 
const machine = createMachine({
  // statechart config goes here
});
ts
import { createMachine } from 'xstate';
 
const machine = createMachine({
  // statechart config goes here
});

States​

You can create these states in XState using the states property:

ts
const machine = createMachine({
  initial: 'asleep',
  states: {
    asleep: {},
    awake: {},
  },
});
ts
const machine = createMachine({
  initial: 'asleep',
  states: {
    asleep: {},
    awake: {},
  },
});

Initial state​

When a state machine starts, it enters the initial state first. A machine can only have one top-level initial state.

In a statechart describing the process of walking the dog, the initial state would be waiting to walk:

ts
const machine = createMachine({
  initial: 'waiting',
  states: {
    waiting: {},
  },
});
ts
const machine = createMachine({
  initial: 'waiting',
  states: {
    waiting: {},
  },
});

Transitions and events​

A machine moves from state to state through 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.

Use the on property inside the desired state to represent its transitions.

ts
const machine = createMachine({
  initial: 'asleep',
  states: {
    asleep: {
      on: {
        'wakes up': {
          target: 'awake',
        },
      },
    },
    awake: {
      on: {
        'falls asleep': {
          target: 'asleep',
        },
      },
    },
  },
});
ts
const machine = createMachine({
  initial: 'asleep',
  states: {
    asleep: {
      on: {
        'wakes up': {
          target: 'awake',
        },
      },
    },
    awake: {
      on: {
        'falls asleep': {
          target: 'asleep',
        },
      },
    },
  },
});

Events​

Define an event with an object using the type attribute to describe the event’s name. Events can also pass in other properties along with their type.

ts
const VALID_EVENTS = [
  {
    type: 'LOG_OUT',
  },
  {
    type: 'LOG_IN',
    /**
     * Pass in any other properties
     * along with the event
     */
    username: 'myusername',
  },
  {
    /**
     * The event type key and value
     * can be any text case
     */
    type: 'wake up',
  },
];
 
const INVALID_EVENTS = [
  {
    /**
     * The event type key must
     * be the same text case as
     * its first instance
     */
    TYPE: 'Some event',
  },
  {
    /**
     * The event type value must
     * be a string
     */
    type: 123,
  },
];
ts
const VALID_EVENTS = [
  {
    type: 'LOG_OUT',
  },
  {
    type: 'LOG_IN',
    /**
     * Pass in any other properties
     * along with the event
     */
    username: 'myusername',
  },
  {
    /**
     * The event type key and value
     * can be any text case
     */
    type: 'wake up',
  },
];
 
const INVALID_EVENTS = [
  {
    /**
     * The event type key must
     * be the same text case as
     * its first instance
     */
    TYPE: 'Some event',
  },
  {
    /**
     * The event type value must
     * be a string
     */
    type: 123,
  },
];

Summary​

A statechart turns boxes and arrows into executable code. The “boxes” are states—the different modes your app can be in. The “arrows” are transitions, letting your statechart know how to move from state to state. Events sent to the statechart can trigger transitions and also pass values to the statechart.

Next, we’ll learn how to make a statechart execute side effects with Options.