Invoke actors
Run a child actor for the lifetime of a state.
XState v6 is in beta
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
onDoneandonErrortransitions handle its completion. - Spawn creates a child whose lifetime you manage.
enq.spawn(...)in a transition function, orspawnin a context initializer, starts the child. It runs until it completes, untilenq.stop(ref)stops it, or until the parent stops. Exiting the state that spawned it does not stop it.
| Invoke | Spawn | |
|---|---|---|
| Lifetime | The invoking state: started on entry, stopped on exit | Until it completes, enq.stop(ref), or the parent stops |
| Declared in | invoke on a state node or the machine root | enq.spawn(...) in a transition function, or spawn in a context initializer |
| How many | Fixed by the config | Any number, decided at runtime |
| Completion handling | onDone, onError, onSnapshot transitions | enq.subscribeTo(...), enq.listen(...) |
| Persistence | Restored with the parent, including inline logic | Restored 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
| Property | Description |
|---|---|
src | Required. The actor logic to run: a logic value, the name of logic registered in actors, or a function that returns either. |
id | Identifier for the child. Defaults to <stateId>:<index>, such as loading:0 for the first invoke of state loading. |
input | Input 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. |
registryKey | Registers the child in the actor registry under that key. |
timeout | Milliseconds, or a function of { context, event } returning milliseconds. |
onTimeout | Transition taken when timeout elapses. Required when timeout is set. |
onDone | Transition taken when the child completes. event.output holds its output. |
onError | Transition taken when the child errors. event.error holds the error. |
onSnapshot | Transition 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 } })
}