Mermaid State Diagram Tutorial (State Machines)

A state diagram models something that can be in one of several states and moves between them in response to events. An order is pending, then paid, then shipped, then delivered; a user account is active, suspended, or closed; a network connection is connecting, connected, or disconnected. State diagrams capture exactly these possibilities and transitions, making them invaluable for modeling anything with a lifecycle. Mermaid's state diagram syntax is clean and lets you write a state machine in text that stays close to the code implementing it.

This tutorial covers defining states, drawing transitions between them, marking the start and end, and the more advanced constructs - composite states that nest, and choice points that branch on a condition. Each concept comes with a snippet you can render in the live editor at /diagram-tools/mermaid-editor. Use the `stateDiagram-v2` keyword, which is the current, improved version of Mermaid's state diagram syntax and the one you should always start with.

States and transitions

A state diagram begins with `stateDiagram-v2`. States are named, and transitions between them are drawn with an arrow: `Still --> Moving` creates two states and a transition from Still to Moving. You label a transition - the event that triggers it - with a colon: `Still --> Moving : go` shows that the "go" event moves the system from Still to Moving. Transition labels are important because they explain why a state change happens, not just that it can.

Every state machine needs a starting point, and Mermaid represents it with the special `[*]` marker. Writing `[*] --> Still` means the machine begins in the Still state. The same `[*]` marker used as a target represents an end state: `Moving --> [*]` means from Moving the machine can terminate. These initial and final pseudo-states render as the standard filled-circle and bullseye markers from UML state diagrams, so the entry and exit points are unmistakable.

Naming states with descriptions

State names are often short identifiers, but you frequently want a longer, more readable label in the diagram. Mermaid lets you separate the identifier from the display text with the `as` keyword: `state "Waiting for payment" as pending` defines a state whose ID is `pending` but which displays "Waiting for payment". You then use the short `pending` ID in transitions, keeping the transition lines concise while the diagram shows friendly labels.

This separation matters more than it first appears. Short IDs make the transition definitions readable and easy to type, while descriptive labels make the rendered diagram clear to someone who did not write it. For a state machine with a dozen states, using clear IDs and descriptive labels is the difference between a diagram that documents the system well and one that only its author can decode.

Composite states and choices

Real systems often have states that contain sub-states. Mermaid supports these composite states by nesting: you write `state Active {` and inside the braces define sub-states and their transitions, closing with `}`. This lets you model, say, an "Active" state that internally has "Idle" and "Processing" sub-states, collapsing detail when you want the big picture and expanding it when you need the internals. Composite states are the main tool for managing complexity in larger state machines.

• `[*]` marks both the initial state (as a source) and a final state (as a target).
• `State1 --> State2 : event` draws a labelled transition triggered by an event.
• `state "Long label" as short` separates a readable label from a concise ID.
• `state Name { ... }` nests sub-states inside a composite state.
• A choice pseudo-state, `state fork <<choice>>`, branches to different states based on a condition.
• Fork and join (`<<fork>>` and `<<join>>`) model concurrent sub-states splitting and rejoining.
• `note right of State : text` attaches an explanatory note to a state.

Choices, notes, and next steps

Sometimes a transition depends on a condition, and Mermaid models this with a choice pseudo-state. You declare one with `state if_state <<choice>>`, then draw transitions into it and out of it with guard conditions as labels - the incoming transition reaches the choice, and the outgoing transitions branch to different states depending on the condition, which you write as the transition label. This keeps conditional branching explicit in the state machine rather than hiding it.

Notes work as in other Mermaid diagrams: `note right of Active : Handles all live requests` attaches explanatory text to a state, letting you document the meaning or behavior of a state beyond its name. Together, these features let Mermaid express genuinely sophisticated state machines in readable text. When you want to lay one out precisely for documentation or a presentation, you can import the Mermaid into Atlas Diagram Studio and refine it visually on the canvas at /diagrams, keeping the text source editable in the Mermaid editor at /diagram-tools/mermaid-editor.