XState Parallel States

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.