Skip to content
Version: XState v5

Parallel states

In statecharts, a parallel state is a state that has multiple child states (also known as regions) that are all active at the same time. This is different from a parent state, where only one child state is active at a time.

Parallel states have the following characteristics:

  • Entering a parallel state will also simultaneously enter all of its regions.
  • Exiting a parallel state will also simultaneously exit all of its regions.
  • An event received in a parallel state is simultaneously received & handled by all of its regions.

Here is a music player example with a parallel state consisting of two regions, one for handling playing the track and one for handling the volume:

import { createMachine, assign } from 'xstate';

const playerMachine = createMachine({
  id: 'player',
  type: 'parallel',
  states: {
    track: {
      initial: 'paused',
      states: {
        paused: {
          on: { PLAY: 'playing' },
        },
        playing: {
          on: { STOP: 'paused' },
        },
      },
    },
    volume: {
      initial: 'normal',
      states: {
        normal: {
          on: { MUTE: 'muted' },
        },
        muted: {
          on: { UNMUTE: 'normal' },
        },
      },
    },
  },
});

Parallel state value​

The state value of a parallel state is an object with the state values of each of its regions.

const playerActor = createActor(playerMachine);
playerActor.start();

console.log(playerActor.getSnapshot().value);
// logs the object:
// {
//   track: 'paused',
//   volume: 'normal'
// }

onDone transition​

Coming soon

Modeling​

Coming soon

  • Avoid transitions between regions
  • Used for separation of concerns that may affect each other (i.e. synchronization)
  • If completely separate, prefer invoke instead

TypeScript​

Coming soon

Cheatsheet​

Coming soon