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 visual diagram. You can click events to trigger transitions and watch the active state update in real time — making it easy to design, test, and reason about state logic before writing a single line of implementation code.

---

How to Use the Visualizer

1. Define your state machine in JSON. The configuration specifies an initial state and a states object where each state defines its outgoing transitions under an on key.
2. Click Initialize Machine. The tool parses the JSON and sets up the machine in its initial state. If the JSON has syntax errors, they're reported clearly.
3. Trigger transitions. Event buttons appear for every event available from the current state. Click an event to fire it and watch the machine move to the next state.
4. Read the diagram. States are shown as nodes with labeled edges representing transitions. The currently active state is highlighted.

---

JSON Configuration Format

{
  "initial": "idle",
  "states": {
    "idle": {
      "on": { "START": "loading" }
    },
    "loading": {
      "on": { "SUCCESS": "active", "ERROR": "failed" }
    },
    "active": {
      "on": { "RESET": "idle" }
    },
    "failed": {
      "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 until reset.

---

Why Model with State Machines

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

Makes transitions explicit. Every possible transition is documented in the configuration. There's no hidden logic or implicit state changes buried in event handlers.

Easier to test. Given a current state and an event, the next state is deterministic. This makes state machines straightforward to unit test exhaustively.

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

---

Common Use Cases

Form wizard flows — multi-step forms with states like step1, step2, review, submitting, success, error

Authentication flows — unauthenticated, authenticating, authenticated, sessionExpired, locked

Media player logic — idle, loading, playing, paused, ended, error

API request lifecycle — idle, loading, success, error, retrying

Onboarding sequences — track user progress through setup steps with clear transitions between completed stages

---

Privacy

State machine configurations are processed entirely in your browser. No JSON or interaction data is sent to any server or stored anywhere.