XState: Predictable UI State with State Machines

Why it exists

Many applications manage complex UI state with a scattered set of boolean flags like isLoading, isSuccess, and isError. This approach often leads to bugs and “impossible states,” such as when both isLoading and isSuccess are accidentally true. State machines provide a formal structure to prevent these bugs by design.

The mental model

Think of an XState machine not as a simple data store, but as a formal blueprint for your component's behavior. It’s a finite state machine where your UI can only be in one defined state at a time (e.g., 'idle', 'loading', 'failed'). Transitions to other states are only triggered by specific, named events. This co-locates your logic from scattered event handlers into a single, predictable, and often visualizable object.

How it works

You define a “machine” using createMachine. This machine configuration includes a finite set of states, an initial state, and a context for storing quantitative data (like a counter or form input). Each state object defines the on events it can respond to. When an event is sent to an instance of the machine (an “actor”), it can trigger actions (like updating the context) and a target transition to a new state. Your UI framework then subscribes to this actor and re-renders whenever the state or context changes.

When to use it

Use XState for components with complex, interdependent states that are difficult to manage with simple variables. It excels in scenarios like multi-step wizards, data fetching UIs (idle, loading, success, error), drag-and-drop interfaces, or any component where the sequence of user actions is critical. It makes complex logic predictable, testable, and robust.

When not to use it

Avoid XState for simple, localized component state. A modal's open/closed status, a single checkbox, or a basic input field's value can often be managed more simply with your framework's built-in state management (like React's useState or Vue's ref). Using a full machine in these cases adds boilerplate without providing significant benefits.

One canonical example

A text input field can be modeled with two states: 'reading' and 'editing'. Initially, it's in 'reading'. An 'text.edit' event transitions it to the 'editing' state. While 'editing', a 'text.change' event updates the input's temporary value in the machine's context. Sending a 'text.commit' event saves the value and transitions back to 'reading'. A 'text.cancel' event discards the changes and also transitions back to 'reading'. This structure prevents bugs like trying to commit changes while not in an editing mode.