Stately

Actions

Enqueue effects during a transition.

XState v6 is in beta

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

Use the enqueue argument from a transition, entry or exit function.

entry: ({ context }, enq) => {
  enq(() => console.log('Entered', context));
}

Transition, entry and exit functions run synchronously while computing the next snapshot. Use their enq argument to queue effects, which run after that computation.

Entry and exit functions also receive stateNode, the state node being entered or exited, and input, the state's input. Transition functions do not receive stateNode.

entry: ({ stateNode }, enq) => {
  enq(() => console.log('Entered', stateNode.id));
}

Built-in actions

MethodPurpose
enq(...)Enqueue an effect function.
enq.raise(...)Send an event to the same actor.
enq.sendTo(...)Send an event to an actor ref or a statically declared child id.
enq.spawn(...)Spawn a child from actor logic or its typed registered name.
enq.stop(...)Stop an actor.
enq.cancel(...)Cancel a delayed event.
enq.log(...)Log values.
enq.emit(...)Emit an actor event.
enq.listen(...)Map another actor's emitted events to events for this machine.
enq.subscribeTo(...)Map another actor's snapshots and outcomes to events for this machine.

Provide reusable named action sources through setup(...).

A named action that has no implementation is undefined in actions, for example when it is only declared in schemas.actions. enq(actions.track) then enqueues nothing: the transition still runs, and development builds log a warning.

enq.sendTo(...) to a missing target (an undefined ref, a child id with no running child, or parent in a root actor) does not error the sender. The event becomes a dead letter with reason 'missingTarget': the root actor's onRejectedEvent option receives it (with reason, targetId and sourceRef) and development builds log a warning that names the sender and the target. A serialized actor ref as the target is delivered to the live actor at its address, or becomes a 'missingTarget' dead letter when no live actor has that address.

Actions are fire-and-forget. XState does not wait for a promise returned by an action. Use invoked async logic when the result changes what happens next.

A function passed to enq(...) runs after the transition has produced the next snapshot, so its return value is ignored: returning { context } from it changes nothing, and development builds warn about it. Context changes come only from what the transition, entry or exit function returns. A named action that computes a context patch is called directly and its result returned; see using named sources.

Use actions for work such as:

  • recording analytics after an order is submitted
  • focusing a field when a form enters an invalid state
  • notifying another actor that a job is ready

TypeScript

Action arguments are inferred from context and event schemas. A child declared in schemas.children can be addressed by id; its actor-ref schema determines which events are accepted.

Actions cheatsheet

entry: (_, enq) => enq(() => startEffect())
exit: (_, enq) => enq(() => stopEffect())
on: {
  ping: (_, enq) => {
    enq.sendTo('worker', { type: 'ping' });
  }
}

On this page