What is the State Machine Visualizer?

A finite state machine (FSM) is a computational model where a system exists in one of a defined set of states at any time, and transitions between states in response to events. State machines are used everywhere in software: UI component logic, form validation flows, authentication sequences, game states, order processing pipelines, and more.

The State Machine Visualizer takes a state machine definition written in JSON and renders it as an interactive diagram. You can fire events to trigger transitions, watch the active state update in real time, track your transition history, and export or share your machine — making it easy to design, test, and communicate state logic before writing a single line of implementation code.

---

How to Use the Visualizer

1. Pick a preset or write your own JSON. Five built-in presets cover the most common patterns: fetch lifecycle, auth flow, traffic light, media player, and form wizard. Load one as a starting point or write your configuration from scratch.
2. Click Initialize Machine. The tool parses your JSON, validates it, and sets the machine to its initial state. Errors are reported specifically — unknown target states, missing initial field, and JSON syntax issues are all caught and described clearly.
3. Send events. Event buttons appear for every transition available from the current state. Each button shows the target state inline so you always know where an event will take you before clicking it.
4. Read the diagram. States appear as nodes with labeled edges representing transitions. The active state is highlighted in blue. The initial state is marked with a small indicator. Parallel edges between the same two states are offset so they never overlap.
5. Review your history. Every transition is logged in the history panel showing the full chain of from, event, and to. Useful for tracing through complex flows or verifying that your machine behaves as expected.
6. Export or share. Download the diagram as an SVG file, or copy a shareable link that encodes your machine configuration in the URL so anyone with the link loads your exact machine.

---

JSON Configuration Format

{
  "initial": "idle",
  "states": {
    "idle": {
      "on": { "FETCH": "loading" }
    },
    "loading": {
      "on": { "SUCCESS": "success", "ERROR": "error" }
    },
    "success": {
      "on": { "RESET": "idle" }
    },
    "error": {
      "on": { "RETRY": "loading", "RESET": "idle" }
    }
  }
}

Each key in states is a state name. The on object maps event names to target states. States with no on key are terminal states — the machine stops there and the tool surfaces a clear message indicating no outgoing transitions remain.

---

Built-in Presets

Fetch lifecycle — the standard async request pattern: idle, loading, success, error, with retry and reset transitions.

Auth flow — models authentication state including session expiry and token refresh: unauthenticated, authenticating, authenticated, expired.

Traffic light — a simple three-state cyclic machine. Good for understanding how circular transitions work.

Media player — covers the full playback lifecycle including error recovery: idle, loading, paused, playing, ended, error.

Form wizard — a multi-step form with back navigation, review, submission, and error handling.

---

Why Model with State Machines

Eliminates impossible states. Without a state machine, UI logic often accumulates boolean flags like isLoading, isError, and isSuccess that can end up in contradictory combinations. A state machine makes impossible combinations structurally impossible — the system can only be in one state at a time.

Makes transitions explicit. Every possible transition is documented in the configuration. There is no hidden logic or implicit state change buried in an event handler or a useEffect chain.

Easier to test. Given a current state and an event, the next state is deterministic. State machines are straightforward to unit test exhaustively because the behavior is a pure function of state and input.

Communicates intent. A state diagram is readable by non-engineers. Sharing a visualized machine is a more effective way to align on UI logic or workflow behavior than describing it in prose or walking through code line by line.

---

Common Use Cases

API request lifecycle — idle, loading, success, error, retrying. The most common pattern in frontend development and the one most developers reach for a state machine to solve first.

Authentication flows — unauthenticated, authenticating, authenticated, sessionExpired, locked. Modeling auth as a state machine makes edge cases like session refresh and lockout explicit rather than scattered across components.

Form wizard flows — multi-step forms with back navigation, validation states, submission, and error recovery. State machines prevent users from reaching review before completing required steps.

Media player logic — idle, loading, playing, paused, ended, error. The combination of async loading and user interaction makes media players a natural fit for explicit state modeling.

Onboarding sequences — track user progress through setup steps with clear transitions between completed stages and well-defined skip or back paths.

Game logic — menu, playing, paused, gameover, victory. Game state is often the first place developers encounter the need for structured state management beyond simple booleans.

---

Privacy

All state machine processing happens entirely in your browser. No configuration data, transition history, or diagram content is sent to any server or stored anywhere. Shareable links encode your machine configuration as a URL parameter — the data lives in the link itself, not on any backend.