>
xstate
Model complex UI logic with XState state machines. Use when a user asks to manage complex multi-step flows, model stateful UI (wizards, forms, auth), prevent impossible states, or implement finite state machines in JavaScript.
#xstate#state-machine#statechart#react#logic
terminal-skillsv1.0.0
Works with:claude-codeopenai-codexgemini-clicursor
Usage
$
✓ Installed xstate v1.0.0
Getting Started
- Install the skill using the command above
- Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
- Reference the skill in your prompt
- The AI will use the skill's capabilities automatically
Example Prompts
- "Review the open pull requests and summarize what needs attention"
- "Generate a changelog from the last 20 commits on the main branch"
Documentation
Overview
XState models application logic as state machines. Instead of managing boolean flags (isLoading, isError, isSuccess), you define states and transitions explicitly — making impossible states impossible. Ideal for complex flows: checkout, onboarding, authentication, multi-step forms.
Instructions
Step 1: Define a Machine
typescript
// machines/authMachine.ts — Authentication state machine
import { setup, assign, fromPromise } from 'xstate'
export const authMachine = setup({
types: {
context: {} as {
user: { id: string; name: string; email: string } | null
error: string | null
retries: number
},
events: {} as
| { type: 'LOGIN'; email: string; password: string }
| { type: 'LOGOUT' }
| { type: 'RETRY' },
},
actors: {
loginUser: fromPromise(async ({ input }: { input: { email: string; password: string } }) => {
const res = await fetch('/api/auth/login', {
method: 'POST',
body: JSON.stringify(input),
})
if (!res.ok) throw new Error('Invalid credentials')
return res.json()
}),
},
}).createMachine({
id: 'auth',
initial: 'idle',
context: { user: null, error: null, retries: 0 },
states: {
idle: {
on: { LOGIN: 'authenticating' },
},
authenticating: {
invoke: {
src: 'loginUser',
input: ({ event }) => ({ email: event.email, password: event.password }),
onDone: {
target: 'authenticated',
actions: assign({ user: ({ event }) => event.output, error: null }),
},
onError: {
target: 'error',
actions: assign({
error: ({ event }) => event.error.message,
retries: ({ context }) => context.retries + 1,
}),
},
},
},
authenticated: {
on: { LOGOUT: { target: 'idle', actions: assign({ user: null }) } },
},
error: {
on: {
RETRY: { target: 'authenticating', guard: ({ context }) => context.retries < 3 },
LOGIN: 'authenticating',
},
},
},
})
Step 2: Use in React
tsx
// components/LoginPage.tsx — XState in React
import { useMachine } from '@xstate/react'
import { authMachine } from '../machines/authMachine'
export function LoginPage() {
const [state, send] = useMachine(authMachine)
if (state.matches('authenticated')) {
return <div>Welcome, {state.context.user.name}!</div>
}
return (
<form onSubmit={(e) => {
e.preventDefault()
const form = new FormData(e.currentTarget)
send({
type: 'LOGIN',
email: form.get('email') as string,
password: form.get('password') as string,
})
}}>
<input name="email" type="email" required />
<input name="password" type="password" required />
{state.matches('error') && (
<p className="error">{state.context.error}</p>
)}
<button disabled={state.matches('authenticating')}>
{state.matches('authenticating') ? 'Signing in...' : 'Sign In'}
</button>
{state.matches('error') && state.context.retries < 3 && (
<button type="button" onClick={() => send({ type: 'RETRY' })}>
Retry ({3 - state.context.retries} left)
</button>
)}
</form>
)
}
Guidelines
- Use XState for complex flows (multi-step forms, checkout, real-time connections). Overkill for simple toggle state.
- State machines prevent impossible states — you can't be "loading" and "error" simultaneously.
- XState Visualizer (stately.ai/viz) renders your machine as a diagram — great for documentation.
- For simple state: Zustand or Jotai. For complex stateful logic: XState.
Information
- Version
- 1.0.0
- Author
- terminal-skills
- Category
- Development
- License
- Apache-2.0