Stately

Invoke actors

Run a child actor for the lifetime of a state.

XState v6 is in beta

APIs and behavior may change before the stable release. Read the stable v5 docs.

Use invoke to start a child actor when a state is entered. The child stops when that state is exited.

const machine = createMachine({
  initial: 'loading',
  states: {
    loading: {
      invoke: {
        src: loadUser,
        input: ({ context }) => ({ id: context.userId }),
        onDone: { target: 'ready' },
        onError: { target: 'failed' },
        timeout: 5_000,
        onTimeout: { target: 'timedOut' }
      }
    },
    ready: {},
    failed: {},
    timedOut: {}
  }
});

Use an actor instead of an action when work is async, can be canceled, sends snapshots or affects the next state. Common examples are payment authorization and file uploads.

Invoke or spawn

Invoking and spawning both create a child actor. They differ in who controls the child's lifetime.

  • Invoke ties the child to a state. Entering the state starts the child, exiting the state stops it, and onDone and onError transitions handle its completion.
  • Spawn creates a child whose lifetime you manage. enq.spawn(...) in a transition function, or spawn in a context initializer, starts the child. It runs until it completes, until enq.stop(ref) stops it, or until the parent stops. Exiting the state that spawned it does not stop it.
InvokeSpawn
LifetimeThe invoking state: started on entry, stopped on exitUntil it completes, enq.stop(ref), or the parent stops
Declared ininvoke on a state node or the machine rootenq.spawn(...) in a transition function, or spawn in a context initializer
How manyFixed by the configAny number, decided at runtime
Completion handlingonDone, onError, onSnapshot transitionsenq.subscribeTo(...), enq.listen(...)
PersistenceRestored with the parent, including inline logicRestored with the parent when the source is registered in actors; inline logic cannot be persisted

Invoke a payment actor for the authorizing state. Spawn one upload actor per selected file, one participant actor per person in a call, or one track actor per queued item in a media player.

Invoke properties

PropertyDescription
srcRequired. The actor logic to run: a logic value, the name of logic registered in actors, or a function that returns either.
idIdentifier for the child. Defaults to <stateId>:<index>, such as loading:0 for the first invoke of state loading.
inputInput for the child: a value, or a function of { context, event, self }. Required when the logic's input type excludes undefined, for example when it declares schemas.input.
registryKeyRegisters the child in the actor registry under that key.
timeoutMilliseconds, or a function of { context, event } returning milliseconds.
onTimeoutTransition taken when timeout elapses. Required when timeout is set.
onDoneTransition taken when the child completes. event.output holds its output.
onErrorTransition taken when the child errors. event.error holds the error.
onSnapshotTransition taken on each child snapshot. event.snapshot holds the snapshot.

Only src is required. A state node accepts a single invoke config or an array of them.

invoke: [
  { src: heartbeat, id: 'heartbeat' },
  { src: syncLogic, id: 'sync', onError: { target: 'offline' } }
]

An input mapper receives the parent machine's typed context and event, including when a registered actor accepts unknown or any input. Actors with a specific input type still check both static inputs and mapper return values.

Typed inline invokes

Use s.createInvoke(...) inside a machine created with s = setup(...) when actor logic is used in one state. It infers the actor's input, completion output, error and snapshot types without registering the actor in setup.actors. For async work, pass the function directly as src and declare its schemas in the same invoke config.

import { setup, types } from 'xstate';

const s = setup({
  schemas: {
    context: types<{ userId: string | undefined; name: string }>()
  },
  states: {
    loading: { schemas: { context: types<{ userId: string }>() } },
    ready: {}
  }
});

const machine = s.createMachine({
  context: { userId: '123', name: '' },
  initial: 'loading',
  states: {
    loading: {
      invoke: s.createInvoke({
        schemas: {
          input: types<{ userId: string }>(),
          output: types<{ name: string }>()
        },
        input: ({ context }) => ({ userId: context.userId }),
        src: async ({ input }) => ({ name: input.userId }),
        onDone: ({ event }) => ({
          target: 'ready',
          context: { name: event.output.name }
        })
      })
    },
    ready: {}
  }
});

Keep the helper call inline: its enclosing state supplies narrowed context, ancestor context, state input and transition targets. In this example, context.userId is string and event.output is { name: string }.

For an async src, schemas.input types the actor input, schemas.output checks the function's resolved value and types onDone.event.output, and schemas.error types onError.event.error. Omit the output schema to infer output from the async return value. The function receives { input, signal, self, system } and the async enqueue object, including emit and step, as createAsyncLogic does. Its input comes from the invoke's static value or input mapper; parent context stays in the mapper and transition handlers.

You can also pass an existing actor logic value, including machine and callback logic:

invoke: s.createInvoke({
  src: loadUserLogic,
  input: ({ context }) => ({ userId: context.userId }),
  onDone: ({ event }) => ({ context: { name: event.output.name } })
})

A bare inline invoke such as { src: loadUserLogic, onDone } cannot correlate that specific logic with its completion output. With no registered actor sources, its onDone.event.output is unknown, so TypeScript requires narrowing before it can be used. For a typed output, use s.createInvoke({ src: loadUserLogic, onDone }) as above, or register the logic in setup({ actors: { loadUserLogic } }) and invoke it with src: 'loadUserLogic'. Prefer one of these typed forms when generating code.

For a logic value, its own schemas determine input, output, error and snapshot types. Declare schemas on that logic rather than repeating them on the invoke.

The helper requires input when the source's input type excludes undefined. Pass a static value or a mapper returning that input type. Logic that accepts undefined can omit input.

Child contracts from schemas.children apply whether declared in setup(...) or s.createMachine(...): supply a declared id and compatible src. This check also applies to hoisted configs when used in the machine.

The helper supports the usual invoke options, including invoke arrays and setups with other registered actors. Child startup, cancellation, timeouts and persistence follow the normal invoke lifecycle.

Keep the source's specific actor logic type to infer its input and output; an AnyActorLogic annotation loses that information. Declare an error schema to type errors; otherwise they are unknown.

A helper call made outside a machine has only setup-level context. To extract a config while keeping a specific state's scope, put the inline helper inside s.createStateConfig('loading', { invoke: s.createInvoke(...) }).

For a helper extracted outside the machine, use function-form onDone: ({ event }) => ({ context: ... }) to infer completion output. A targetless object-form onDone.context mapper needs an explicit argument annotation.

Actor lifecycle

Invoked actors belong to the state that starts them:

  • entering the state starts the actor
  • leaving the state stops it
  • re-entering the state stops the old actor and starts a new one

A state is re-entered by an external transition back to itself, or by a transition with reenter: true. A transition that stays inside the invoking state does not restart the child.

Invoke on the machine root runs for the whole lifetime of the actor. Root invocations survive ordinary transitions between top-level states, and restart only on a root transition with reenter: true.

const machine = createMachine({
  invoke: { src: connection, id: 'connection' },
  initial: 'idle',
  states: { idle: {}, playing: {} }
});

Children are started after the parent snapshot is committed, so a child that immediately sends an event to its parent finds the parent already in the invoking state.

Choosing logic

Invoke a machine when the child has states of its own:

checkout: {
  invoke: {
    src: paymentMachine,
    id: 'payment',
    input: ({ context }) => ({ amount: context.total }),
    onDone: { target: 'confirmed' }
  }
}

Invoke async logic for a single request. The child completes with the resolved value and errors with a rejection:

const chargeCard = createAsyncLogic({
  run: ({ input, signal }) => createCharge(input.amount, { signal })
});

Invoke callback logic for a subscription that lives as long as the state:

playing: {
  invoke: {
    src: createCallbackLogic(({ sendBack }) => {
      const id = setInterval(() => sendBack({ type: 'tick' }), 1000);
      return () => clearInterval(id);
    })
  },
  on: { tick: ({ context }) => ({ context: { time: context.time + 1 } }) }
}

Reacting to the child

onDone receives final output, onError an unhandled error, and onSnapshot each intermediate snapshot.

invoke: {
  src: uploadMachine,
  onSnapshot: ({ context, event }) => ({
    context: {
      ...context,
      progress: event.snapshot.context.progress
    }
  }),
  onDone: { target: 'complete' },
  onError: { target: 'failed' }
}

These are conveniences over lifecycle events. The child sends xstate.done.actor, xstate.error.actor and xstate.snapshot.actor events with an actorId payload; onDone, onError and onSnapshot set matches: { actorId } for you so each one only handles its own child. Handle the event directly when the transition belongs on an ancestor state:

on: {
  'xstate.done.actor': { matches: { actorId: 'payment' }, target: 'confirmed' }
}

See transitions for matches and the full list of lifecycle events.

Timing out an invocation

timeout bounds how long the invocation may run. When it elapses, onTimeout is taken. A handler that exits the owning state stops the child; a targetless handler leaves it running unless it calls enq.stop(...). When the child finishes first, the timeout is canceled.

authorizing: {
  invoke: {
    src: authorizePayment,
    timeout: ({ context }) => context.authTimeout,
    onTimeout: { target: 'declined' },
    onDone: { target: 'authorized' }
  }
}

Setting timeout without onTimeout throws when the machine is created in development builds. Use createAsyncLogic({ timeout }) instead when the timeout belongs to the logic rather than to this particular invocation. See timeouts.

Referencing the child

Invoked children appear on snapshot.children under their id, and transition functions receive them as children:

on: {
  cancel: ({ children }, enq) => {
    enq.sendTo(children.payment, { type: 'cancel' });
  }
}

A child sends events back through its parent argument:

const paymentMachine = createMachine({
  on: {
    approve: ({ parent }, enq) => {
      enq.sendTo(parent, { type: 'paymentApproved' });
    }
  }
});

Persistence

Invoked children are persisted with the parent snapshot and restored by restoreActor(machine, persisted) from xstate/persist. A child restored this way keeps its context but gets a new session.

Register logic in actors and reference it by name when the persisted snapshot should stay readable and stable across refactors:

const machine = createMachine({
  actors: { chargeCard },
  initial: 'charging',
  states: {
    charging: { invoke: { src: 'chargeCard', id: 'charge' } }
  }
});

The persisted child then records src: 'chargeCard' instead of a generated source name that points back at this invoke config. Either restores, but a named source survives moving the invoke to another state. See persistence.

Common pitfalls

Invoke belongs to the state, not to the transition that led there. This is wrong:

on: {
  submit: {
    target: 'sending',
    // ❌ invoke is not a transition property
    invoke: { src: sendOrder }
  }
}

Put the invoke on the target state instead, so the actor starts when sending is entered and stops when it is left.

Invoke also is not the right tool when the child must outlive the state, or when the number of children is dynamic. Spawn those instead.

TypeScript

Provide named actor logic through setup({ actors }) or createMachine({ actors }). XState correlates src with input, so a static or mapped input is checked against that logic's input type, and onDone sees the output type of that logic.

For a literal invoke id and a named or inline actor source, XState infers the child reference in snapshot.children. The child may be absent when the invoke state is inactive, so check for undefined before sending an event:

import { createActor, setup, types } from 'xstate';

const paymentMachine = setup({
  schemas: { events: { retry: types<{}>() } }
}).createMachine({ initial: 'idle', states: { idle: {} } });

const parent = setup({ actors: { paymentMachine } }).createMachine({
  invoke: { id: 'payment', src: 'paymentMachine' }
});

const payment = createActor(parent).getSnapshot().children.payment;
payment?.send({ type: 'retry' });

Declare child ids with schemas.children when the child contract must also be available inside machine callbacks. This also checks that each declared id receives compatible logic. For dynamic IDs, keep the returned child reference from enq.spawn(...) in context instead of indexing snapshot.children with an arbitrary string. Spawned children have a separately managed lifetime; see Spawn:

setup({}).createMachine({
  schemas: {
    children: {
      payment: z.custom<ActorRefFrom<typeof paymentMachine>>()
    }
  },
  invoke: { id: 'payment', src: paymentMachine }
});

children.payment is then typed, children.other is a type error, and invoking incompatible logic under id: 'payment' is rejected. The id can also be used directly with enq.sendTo; the event is checked against the declared actor ref:

on: {
  retry: (_, enq) => {
    enq.sendTo('payment', { type: 'retry' });
  }
}

Typed done and error events

When children are declared in schemas.children, entry, exit and transition functions that can receive any event include xstate.done.actor and xstate.error.actor in their event type, narrowed by actorId. After narrowing, event.actorId is the declared id and event.output has the child's output type. event.error is unknown. A handler under on for a user event, such as on.retry, still receives only that event.

setup({
  actors: { fetchUser },
  schemas: {
    events: { retry: z.object({}) },
    children: {
      fetch: z.custom<ActorRefFrom<typeof fetchUser>>()
    }
  }
}).createMachine({
  invoke: { id: 'fetch', src: 'fetchUser' },
  entry: ({ event }) => {
    assertEvent(event, 'xstate.done.actor');
    event.actorId; // 'fetch'
    event.output.name; // string
  }
});

Without schemas.children, these events are not part of the event type. Declaring schemas.events is not required for the narrowing.

Invoke cheatsheet

invoke: {
  id: 'request',
  src: requestLogic,
  input: ({ context }) => context.request,
  registryKey: 'request',
  timeout: 10_000,
  onTimeout: { target: 'timedOut' },
  onDone: { target: 'success' },
  onError: { target: 'failure' },
  onSnapshot: ({ event }) => ({ context: { snapshot: event.snapshot } })
}

On this page