Examples

The examples directory of the XState repository contains runnable projects. Each one is a small application you can clone and run with pnpm install && pnpm dev (or pnpm start, depending on the example).

These examples use XState v6 syntax: transition functions that return { target, context }, createAsyncLogic(...) and createCallbackLogic(...) instead of promise and callback actors, and guards written as return undefined. Some were migrated from v5 mechanically and still read more verbosely than code you would write by hand, and a few keep a v5 helper here and there. When something in an example does not match the reference pages, the reference pages are correct. See the migration guide for how the older shapes map onto the new ones.

Start here

• counter — the smallest useful machine: increment and decrement transitions updating one context value, wired to plain DOM.
• toggle — two states and one event, with no context at all.
• fetch — idle / loading / success / failure around createAsyncLogic(...) invoked by the loading state.

UI patterns

• stopwatch — createCallbackLogic(...) invoked by the running state sends a tick every 10ms; leaving the state clears the interval.
• timer — the same ticking pattern, plus events that adjust the duration while the timer is stopped.
• tiles — a sliding tile puzzle with named guards deciding whether two tiles are adjacent.
• snake-react — a game loop as an invoked callback actor, with the whole board in context.
• tic-tac-toe-react — turn taking and win detection in a playing state, with a RESET transition on the machine root.
• todomvc-react — the TodoMVC spec, with the todo list and the active filter held in context.
• friends-list-react — a parent machine that spawns one child actor per friend and keeps their refs in context.
• trivia-game-example — a quiz whose navigation actions are supplied with machine.provide(...) so the machine stays free of router imports.

7GUIs

Ports of the 7GUIs benchmark tasks, in React and Vue:

• 7guis-counter-react and 7guis-1-counter-vue — the counter task.
• 7guis-temperature-react and 7guis-2-temperature-vue — two fields that convert into each other without looping.
• 7guis-flight-booker-react — trip type, date validation and a booking request as invoked async logic.

XState Store

XState Store examples, for state that needs events but not states:

• store-counter-react — a module-level store read with useSelector.
• local-store-counter-react — the same store created per component with useStore.
• store-tic-tac-toe — a full game in one store, including derived win and draw outcomes.

Backends and persistence

• express-workflow — an Express API that starts a workflow, restores it from a persisted snapshot on each request, sends the event and persists the result. The pattern behind backend workflows.
• persisted-donut-maker — a multi-step recipe machine whose snapshot is written to disk and restored on the next run.
• mongodb-persisted-state — the same machine with MongoDB as the snapshot store, plus a queue that serializes writes.
• mongodb-credit-check-api — a credit check API where each external service is createAsyncLogic(...) with a Zod input schema.

Serverless Workflow ports

Ports of the Serverless Workflow specification examples, each a single runnable main.ts. They are the densest collection of workflow shapes in the repository. Use them to see how a particular orchestration pattern looks as a statechart.

• workflow-hello — the minimum: one final state with output.
• workflow-async-function — one invoked async function with typed input taken from the workflow's own input.
• workflow-parallel — two branches running at once, joining when both are done.
• workflow-event-based — waiting for one of several events, with a named delay as the deadline.
• workflow-check-inbox — a root-level callback actor that sends a reminder event on an interval, driving a check-then-notify cycle back to Idle.
• workflow-credit-check and workflow-applicant-request — decision workflows that branch on the result of an invoked service.
• workflow-book-lending — a long-running flow that waits on human events between service calls, with a delayed transition for the wait and a nested checkout region.
• workflow-provision-orders — order provisioning with a nested Exception state whose children handle each kind of missing field.
• workflow-purchase-order-deadline — a deadline on the whole order, with retries handled by an external retry policy library.
• workflow-car-vitals — several checks invoked together while the car is on, re-run on a delayed transition.
• workflow-accumulate-room-readings — readings collected into context until a delayed transition ends the window and reports them.
• workflow-monitor-patient — a single monitoring state whose event handlers react to each kind of vital sign alert.
• workflow-media-scanner — a file scanning pipeline split across modules.

The remaining workflow-* directories cover the rest of the specification's examples: workflow-async-subflow, workflow-car-auction-bids, workflow-event-based-service, workflow-event-greeting, workflow-filling-water, workflow-finalize-college-app, workflow-greeting, workflow-math-problem, workflow-monitor-job, workflow-new-patient-onboarding, workflow-reusing-functions and workflow-send-cloudevent.

Contributing an example

See the examples readme for how to scaffold a new example and open a pull request.

What next?

• Get running with the quick start.
• Build your first machine step by step.
• Use XState with your framework.
• Migrate an existing v5 codebase.