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' },
        },
      },
    },
  },
});

Using states in Stately Studio​

A dashed line borders each region.

In the video player machine above, the video and audio states are active at the same time, which means the following combinations of states can happen simultaneously:

  • video playing, audio muted
  • video playing, audio unmuted
  • video stopped, audio muted
  • video stopped, audio unmuted

Make a state a parallel state​

First, select the parent state you want to set as a parallel state. Then…

Using the quick actions menu:​

  1. Right-click the state to bring up the quick actions menu.
  2. Choose Parallel from the Type options.

Using the State details panel:​

  1. Select the parent state you want to set as the parallel state.
  2. Open the State details panel from the right tool menu.
  3. Choose Parallel from the Type dropdown menu.

Parallel state value​

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

const playerActor = interpret(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