Skip to content
Version: XState v5

Invoke

XState is based on the actor model. Invoked actors are managed by the state machine. Invoked actors are created and started when the state is entered, and stopped when the state is exited.

Coming soon… invoking an actor: { invoke: { src: ... } }.

  • Actors can also be invoked on the root of the machine. They last the lifetime of the machine

Coming soon… example of invoking an actor at root.

↓Jump to learning more about the invoked actors API in XState↓

Using invoked actors in Stately Studio​

Invoked actors are are labeled on their invoking state with “Invoke /” followed by the actor’s source name and ID.

You can invoke multiple actors on a single state. Top-level final states cannot have invoked actors.

In the video player above, the startVideo actor is invoked when the video player is in the Opened state.

Invoke actors on a state​

  1. Select the state you want to invoke an actor.
  2. Open the State details panel from the right tool menu.
  3. Use the + plus icon alongside the Invoked actors to add a new action.
  4. Add the source for the actor using the src text input.
  5. Add the ID for the actor using the ID text input.
  6. Save the invoked actor using the Save button.

Invoke done events​

An invoke done event transitions from a state once its invocation has been completed. An invoke done event is labeled “done:” followed by the invocation’s ID.

How to create invoke done events in Stately Studio​

  1. Select the state with an invoked actor where you want to add an invoke done event.
  2. Drag from the handles on the left, right and bottom sides of the selected state, and release to create a connecting transition, event and new state.
  3. The newly-created event will automatically be created as an invoke done event.

You can also change an existing event into an invoked done event using the quick actions menu:

  1. Select the existing event you wish to change into an invoke done event.
  2. Right-click the state to bring up the quick actions menu.
  3. Choose Invocation done event from the Event type options.

Invoke error events​

An invoke error event transitions from a state when an error occurs in its invocation. An invoke error event is labeled “error:” followed by the invocation’s ID.

How to create invoke error events in Stately Studio​

  1. Select the state with an invoked actor where you want to add an invoke error event.
  2. Drag from the handles on the left, right and bottom sides of the selected state, and release to create a connecting transition, event and new state.
  3. The newly-created event will automatically be created as an invoke done event.
  4. When an invoke done event already exists from that state, creating another event will automatically create that event as an invoke error event.

You can also change an existing event into an invoked error event using the quick actions menu:

  1. Select the existing event you wish to change into an invoke error event.
  2. Right-click the state to bring up the quick actions menu.
  3. Choose Invocation error event from the Event type options.

API​

  • invoke: { src: ... } - Invokes an actor.
    • src - The actor to invoke.
    • id - The ID of the actor.
    • input - The input to pass to the actor.
    • systemId - system-wide ID
    • onDone
    • onSnapshot
    • onError

Source​

  • Represented by src
  • Can be inline: src: fromPromise(...)
  • Can be referenced: src: 'fetchUser'
  • .provide({ actors: ... })

Lifecycle​

Invoked actors have a lifecycle that is managed by the parent machine. They are created and started when the state is entered, and stopped when the state is exited.

  • Transitions that reenter the state stop invoked actors and start new invoked actors.
    • Don't want this? Set reenter: false or omit reenter altogether.

Actor refs​

Actors can be read on state.children.<actorId>. The returned value is an ActorRef object, and it has these properties:

  • id - the ID of the actor
  • send()
  • getSnapshot()

Actor snapshots​

The actor snapshot is the latest emitted value from the actor. It can be read from actorRef.getSnapshot().

  • The snapshot is not the same as the internal state; it is what the actor chooses to share with observers.

onDone​

  • Transitions when invoked actor is complete
  • Event gets .output with actor's output data

onSnapshot​

  • Transitions when invoked actor emits a new snapshot
  • Event gets data with actor's snapshot

onError​

  • Transitions when invoked actor throws an error
  • Event gets data with actor's error data

Input​

  • Actors can receive input. This is an event: { type: 'xstate.init', input: ... }

Kinds of actors​

TypeScript​

Coming soon

Cheatsheet​

Coming soon