State machines

Learn how to use state machines in XState and Stately Studio.

• State machines

  A state machine is a model that describes the behavior of something, for example an actor. Finite state machines describe how the state of an actor transitions to another state when an event occurs.

• Setup

  In XState version 5, you can now use the setup({ ... }) function to setup types and sources for your machines. This has many benefits:

• State

  A state describes the machine’s status or mode, which could be as simple as Paused and Playing. A state machine can only be in one state at a time.

• Context

  In XState, context is how you store data in a state machine actor.

• Input

  Input refers to the data provided to a state machine that influences its behavior. In XState, you provide input when creating an actor using the second argument of the createActor(machine, { input }) function:

• Output

  Output refers to the final data that an actor produces. When an actor is responsible for performing some task, such as making a network request or running complex calculations, it will return output once it finishes that task. The output represents the result of the actor’s work. Actors only produce output when their status is “done”; i.e. when they are in their final state.

• Events and transitions

  A transition is a change from one finite state to another, triggered by an event.

• Eventless (always) transitions

  Eventless transitions are transitions that happen without an explicit event. These transitions are always taken when the transition is enabled.

• Delayed (after) transitions

  Delayed transitions are transitions that are triggered after a set amount of time. Delayed transitions are useful for building timeouts and intervals into your application logic. If another event occurs before the end of the timer, the transition doesn’t complete.

• Actions

  Actions are fire-and-forget effects. When a state machine transitions, it may execute actions. Actions occur in response to events, and are typically defined on transitions in the actions [...] property, or for any transition that exits a state in the state's exit: [...] property.

• Guards

  A guard is a condition function that the machine checks when it goes through an event. If the condition is true, the machine follows the transition to the next state. If the condition is false, the machine follows the rest of the conditions to the next state.

• Initial states

  When a state machine starts, it enters the initial state first. A machine can only have one top-level initial state; if there were multiple initial states, the machine wouldn’t know where to start!

• Finite states

  A finite state is one of the possible states that a state machine can be in at any given time. It’s called “finite” because state machines have a known limited number of possible states. A state represents how a machine “behaves” when in that state; its status or mode.

• Parent states

  States can contain more states, also known as child states. These child states are only active when the parent state is active.

• Parallel states

  In statecharts, a parallel state is a state that has multiple child states (also known as regions) that are all active at the same time. This is different from a parent state, where only one child state is active at a time.

• Final states

  A final state is a state that represents the completion or successful termination of a machine. It is defined by the type

• History states

  A history state is a special type of state (a pseudostate) that remembers the last child state that was active before its parent state is exited. When a transition from outside the parent state targets a history state, the remembered child state is entered.

• Persistence

  Actors can persist their internal state and restore it later. Persistence refers to storing the state of an actor in persistent storage, such as localStorage or a database. Restoration refers to restoring the state of an actor from persistent storage.

• Tags

  State nodes can have tags, which are string terms that help group or categorize the state node. For example, you can signify which state nodes represent states in which data is being loaded by using a "loading" tag, and determine if a state contains those tagged state nodes with state.hasTag(tag):

• Event emitter

  Since XState version 5.9.0