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…

On the canvas​

  1. Right-click the state to open the edit menu.
  2. From the Type options, choose Parallel.

Using the state Details panel​

  1. Select the parent state you want to make a parallel state.
  2. Open the state Details panel from the right tool menu.
  3. From the type option, choose Parallel.

To set the state back as a normal state, follow the same steps and select the Normal type option.

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