XState Parallel States

Model concurrent, independent state regions that are active simultaneously within a single machine

When to Use

• A UI has independent concerns that change independently (e.g., bold AND italic in a text editor)
• Modeling multiple concurrent processes (upload progress + validation status)
• Avoiding combinatorial explosion of states when combining orthogonal dimensions
• A form with independent section-level validation that proceeds in parallel

Instructions

1. Set

   type: 'parallel'

   on the parent state node. All direct child states become active simultaneously.
2. Each child region operates independently — events are processed by all active regions.
3. Parallel states do not have an

   initial

   property — all children start in their own

   initial

   states simultaneously.
4. Transitions can target states in other regions using the full state ID path.
5. Use

   onDone

   on the parallel parent to react when ALL child regions reach their final states.
6. Keep each parallel region focused on one concern. If regions need heavy coordination, consider using a single compound state instead.

// text-editor.machine.ts
import { createMachine } from 'xstate';

const textEditorMachine = createMachine({
  id: 'editor',
  type: 'parallel',
  states: {
    bold: {
      initial: 'off',
      states: {
        off: { on: { TOGGLE_BOLD: 'on' } },
        on: { on: { TOGGLE_BOLD: 'off' } },
      },
    },
    italic: {
      initial: 'off',
      states: {
        off: { on: { TOGGLE_ITALIC: 'on' } },
        on: { on: { TOGGLE_ITALIC: 'off' } },
      },
    },
    underline: {
      initial: 'off',
      states: {
        off: { on: { TOGGLE_UNDERLINE: 'on' } },
        on: { on: { TOGGLE_UNDERLINE: 'off' } },
      },
    },
  },
});

// State value when bold is on, italic off, underline on:
// { bold: 'on', italic: 'off', underline: 'on' }

// Multi-step upload with parallel validation
const uploadMachine = createMachine({
  id: 'upload',
  initial: 'preparing',
  states: {
    preparing: {
      on: { START: 'processing' },
    },
    processing: {
      type: 'parallel',
      states: {
        upload: {
          initial: 'uploading',
          states: {
            uploading: {
              invoke: { src: 'uploadFile', onDone: 'done', onError: 'error' },
            },
            done: { type: 'final' },
            error: {},
          },
        },
        validation: {
          initial: 'validating',
          states: {
            validating: {
              invoke: { src: 'validateFile', onDone: 'done', onError: 'error' },
            },
            done: { type: 'final' },
            error: {},
          },
        },
      },
      // Fires when BOTH upload and validation reach 'done'
      onDone: 'complete',
    },
    complete: { type: 'final' },
  },
});

Details

State values: For parallel states,

state.value

is an object where each key is a region name and each value is that region's current state. For nested parallels, values nest further.

Event handling: When an event is received, it is processed by ALL active regions. If both

bold

and

italic

handle

RESET

, both will transition. Be intentional about event naming to avoid unintended cross-region effects.

onDone completion: A parallel state's

onDone

fires only when every child region has reached a

final

state. If any region stays active, the parallel state stays active.

Without parallel states (combinatorial explosion): Modeling bold + italic + underline without parallel states would require 8 atomic states (off-off-off, on-off-off, ...). With parallel states, you need 6 (2 per region). This scales linearly instead of exponentially.

Transitions between regions: A region can target another region's state via a full ID path, but this is generally a code smell. If regions need tight coordination, they may not be truly parallel — consider a compound state instead.

Testing parallel machines: Check

state.value

as an object:

expect(state.value).toEqual({ bold: 'on', italic: 'off' })

.

Source

https://stately.ai/docs/parallel-states

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.