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​

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​

First, select the state where you want to invoke an actor.

On the canvas​

  1. Select the state where you want to invoke an actor.
  2. Use the plus icon button to open the edit menu.
  3. Choose Invoked actor from the menu to add an invoked actor block to the event.
  4. Write your actor’s source in the invoked actors’s text input.

Add actor source logic and ID​

  1. Use the edit icon button to open the Invoked actor panel.
  2. Enter the actor’s source logic in the Source logic text input.
  3. Enter the actor’s ID in the Actor ID text input.

Using the event details panel​

  1. Select the state where you want to invoke an actor.
  2. Open the state Details panel from the right tool menu.
  3. Use the + Effect button to open the effects menu, and choose Add invoked actor.
  4. Use the edit icon button to open the Invoked actor panel.
  5. Enter the actor’s source logic in the Source logic text input.
  6. Enter the actor’s ID in the Actor ID text input.

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. Press or drag from one of 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 edit menu. The source state must have an invoked actor.

  1. Select the existing event you wish to change into an invoke done event.
  2. Right-click the state to open the edit menu.
  3. From the Event type options, choose Invocation done event.

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. Press or drag from one of 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 edit menu. The source state must have an invoked actor.

  1. Select the existing event you wish to change into an invoke error event.
  2. Right-click the state to open the edit menu.
  3. From the Event type options, choose Invocation error event.

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