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:

const feedbackMachine = createMachine({
  id: 'feedback',

  // Initial state
  initial: 'prompt',

  // Finite states
  states: {
    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 (1m17s).

Specifying an initial state

Typically, a state machine will have multiple finite states that it can be in. The initial property on the machine config specifies the initial state that the machine should start in.

Parent states also must specify an initial state in their initial property. The following trafficLightMachine will start in the 'green' state, as it is specified in the initial property of the machine config.

When the machine reaches the 'red' parent state, it will also be in the 'red.walk' state, as it is specified in the initial property of the 'red' state.

import { createMachine } from 'xstate';

const trafficLightMachine = createMachine({
  initial: 'green',
  states: {
    green: {/* ... */},
    yellow: {/* ... */},
    red: {
      initial: 'walk',
      states: {
        walk: {/* ... */},
        wait: {/* ... */},
        stop: {/* ... */},
      }
    },
  }
});

const trafficLightActor = createActor(trafficLightMachine);

trafficLightActor.subscribe(state => {
  console.log(state.value);
});

trafficLightActor.start();
// logs 'green'