setup

Configures and creates a type-safe state machine builder with predefined implementations for actions, guards, actors, and delays. The setup() function is the recommended way to create state machines in XState v5, as it provides excellent TypeScript type inference and allows you to define reusable implementations.

Signature

function setup<
  TContext extends MachineContext,
  TEvent extends AnyEventObject,
  TActors extends Record<string, UnknownActorLogic>,
  TChildrenMap extends Record<string, string>,
  TActions extends Record<string, ParameterizedObject['params'] | undefined>,
  TGuards extends Record<string, ParameterizedObject['params'] | undefined>,
  TDelay extends string,
  TTag extends string,
  TInput,
  TOutput extends NonReducibleUnknown,
  TEmitted extends EventObject,
  TMeta extends MetaObject
>({
  types,
  actors,
  actions,
  guards,
  delays
}): SetupReturn<...>

Parameters

config

object

required

Configuration object for the machine setup.

Show properties

types

SetupTypes

Type definitions for TypeScript inference. This is a compile-time only property.

types: {} as {
  context: { count: number };
  events: { type: 'INCREMENT' } | { type: 'DECREMENT' };
  input: { initialCount: number };
  output: number;
}

actors

Record<string, ActorLogic>

A map of actor logic creators that can be invoked or spawned.

actors: {
  fetchUser: fromPromise(async ({ input }) => {
    const response = await fetch(`/api/users/${input.userId}`);
    return response.json();
  })
}

actions

Record<string, ActionFunction>

A map of action implementations that can be referenced by name.

actions: {
  logMessage: ({ context, event }) => {
    console.log(context.message, event);
  }
}

guards

Record<string, GuardPredicate>

A map of guard (condition) implementations that can be referenced by name.

guards: {
  isPositive: ({ context }) => context.count > 0,
  isEven: ({ context }) => context.count % 2 === 0
}

delays

Record<string, DelayConfig>

A map of delay values or functions for delayed transitions and actions.

delays: {
  SHORT: 1000,
  LONG: ({ context }) => context.timeout
}

Returns

setupReturn

SetupReturn

An object with methods for creating machines and type-safe helpers.

Show methods

createMachine

function

Creates a state machine with the configured types and implementations.

createMachine(config: MachineConfig): StateMachine

extend

function

Returns a new setup with additional actions, guards, and delays merged with existing ones.

extend({ actions?, guards?, delays? }): SetupReturn

assign

function

Type-safe version of the assign action creator.

sendTo

function

Type-safe version of the sendTo action creator.

raise

function

Type-safe version of the raise action creator.

log

function

Type-safe version of the log action creator.

cancel

function

Type-safe version of the cancel action creator.

stopChild

function

Type-safe version of the stopChild action creator.

enqueueActions

function

Type-safe version of the enqueueActions action creator.

emit

function

Type-safe version of the emit action creator.

spawnChild

function

Type-safe version of the spawnChild action creator.

createStateConfig

function

Creates a type-safe state config that can be reused in multiple machines.

createAction

function

Creates a type-safe action implementation.

Examples

Basic setup with types

import { setup, createActor } from 'xstate';

const counterMachine = setup({
  types: {} as {
    context: { count: number };
    events: { type: 'INCREMENT' } | { type: 'DECREMENT' };
  }
}).createMachine({
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      on: {
        INCREMENT: {
          actions: assign({
            count: ({ context }) => context.count + 1
          })
        },
        DECREMENT: {
          actions: assign({
            count: ({ context }) => context.count - 1
          })
        }
      }
    }
  }
});

Setup with actions and guards

import { setup } from 'xstate';

const feedbackMachine = setup({
  types: {} as {
    context: { feedback: string; retries: number };
    events: 
      | { type: 'SUBMIT' }
      | { type: 'RETRY' }
      | { type: 'CANCEL' };
  },
  actions: {
    logSubmission: ({ context }) => {
      console.log('Submitting feedback:', context.feedback);
    },
    incrementRetries: assign({
      retries: ({ context }) => context.retries + 1
    }),
    clearRetries: assign({
      retries: 0
    })
  },
  guards: {
    canRetry: ({ context }) => context.retries < 3,
    hasValidFeedback: ({ context }) => context.feedback.length > 0
  }
}).createMachine({
  initial: 'editing',
  context: { feedback: '', retries: 0 },
  states: {
    editing: {
      on: {
        SUBMIT: {
          guard: 'hasValidFeedback',
          target: 'submitting'
        }
      }
    },
    submitting: {
      entry: 'logSubmission',
      on: {
        SUCCESS: {
          target: 'success',
          actions: 'clearRetries'
        },
        ERROR: {
          guard: 'canRetry',
          target: 'editing',
          actions: 'incrementRetries'
        }
      }
    },
    success: {
      type: 'final'
    }
  }
});

Setup with actors

import { setup, fromPromise } from 'xstate';

const userMachine = setup({
  types: {} as {
    context: { user: User | null };
    events: { type: 'FETCH'; userId: string };
  },
  actors: {
    fetchUser: fromPromise(async ({ input }: { input: { userId: string } }) => {
      const response = await fetch(`/api/users/${input.userId}`);
      return response.json();
    })
  }
}).createMachine({
  initial: 'idle',
  context: { user: null },
  states: {
    idle: {
      on: {
        FETCH: 'loading'
      }
    },
    loading: {
      invoke: {
        src: 'fetchUser',
        input: ({ event }) => ({ userId: event.userId }),
        onDone: {
          target: 'success',
          actions: assign({
            user: ({ event }) => event.output
          })
        },
        onError: 'failure'
      }
    },
    success: {},
    failure: {}
  }
});

Setup with delays

import { setup } from 'xstate';

const timeoutMachine = setup({
  types: {} as {
    context: { timeout: number };
    events: { type: 'START' } | { type: 'RESET' };
  },
  delays: {
    SHORT: 1000,
    LONG: 5000,
    DYNAMIC: ({ context }) => context.timeout
  }
}).createMachine({
  initial: 'idle',
  context: { timeout: 3000 },
  states: {
    idle: {
      on: {
        START: 'waiting'
      }
    },
    waiting: {
      after: {
        DYNAMIC: 'done'
      },
      on: {
        RESET: 'idle'
      }
    },
    done: {
      type: 'final'
    }
  }
});

Using extend

import { setup } from 'xstate';

const baseSetup = setup({
  types: {} as {
    context: { count: number };
    events: { type: 'INCREMENT' };
  },
  actions: {
    logCount: ({ context }) => {
      console.log(context.count);
    }
  }
});

const extendedSetup = baseSetup.extend({
  actions: {
    logDouble: ({ context }) => {
      console.log(context.count * 2);
    }
  }
});

const machine = extendedSetup.createMachine({
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      entry: ['logCount', 'logDouble']
    }
  }
});

Using input and output types

import { setup } from 'xstate';

const calculatorMachine = setup({
  types: {} as {
    context: { total: number };
    input: { initialValue: number };
    output: number;
    events: { type: 'ADD'; value: number };
  }
}).createMachine({
  initial: 'calculating',
  context: ({ input }) => ({
    total: input.initialValue
  }),
  states: {
    calculating: {
      on: {
        ADD: {
          actions: assign({
            total: ({ context, event }) => context.total + event.value
          })
        },
        FINISH: 'done'
      }
    },
    done: {
      type: 'final'
    }
  },
  output: ({ context }) => context.total
});

const actor = createActor(calculatorMachine, {
  input: { initialValue: 10 }
});
actor.start();
actor.send({ type: 'ADD', value: 5 });

Notes

The types property is used solely for TypeScript type inference and has no runtime behavior
Actions, guards, actors, and delays defined in setup can be referenced by their string keys in the machine configuration
Using setup() is recommended over passing implementations as a second argument to createMachine()
The extend() method allows for composition and reuse of configurations

Core API

Actions

Guards

Actors

Utilities

Signature

Parameters

Returns

Examples

Basic setup with types

Setup with actions and guards

Setup with actors

Setup with delays

Using extend

Using input and output types

Notes

See also

Build docs developers (and LLMs) love

Core API

Actions

Guards

Actors

Utilities

Documentation Index

​Signature

​Parameters

​Returns

​Examples

​Basic setup with types

​Setup with actions and guards

​Setup with actors

​Setup with delays

​Using extend

​Using input and output types

​Notes

​See also

Build docs developers (and LLMs) love

Signature

Parameters

Returns

Examples

Basic setup with types

Setup with actions and guards

Setup with actors

Setup with delays

Using extend

Using input and output types

Notes

See also