Mermaid State Diagram: Syntax, Examples & Templates
Open state diagram in the editor
A state diagram models the modes a single thing can be in and the events that move it between them. Where a flowchart follows a person through a process, a state diagram follows one object — an order, a session, a draft document — across its entire life. If you can name the states and the events, you can draw the diagram.
Basic syntax
The declaration is stateDiagram-v2; always use the v2 form, which has the cleaner rendering and arrowheads. States need no separate declaration — the first transition that mentions them creates them. The line [*] --> Draft defines both the entry point and the Draft state at once, and every other transition is written From --> To: event, where the text after the colon names the event that triggers the change. Using [*] as the target of a transition marks a terminal state, and a diagram may have several of them, as the bike rental example does.
States and transitions
Good state diagrams are exhaustive about outcomes. For every state, ask what events can arrive there and make sure each one has an arrow — the publishing example would be wrong without the “request changes” path back to Draft, because in reality reviews do fail. Event labels are optional but strongly recommended: an unlabeled arrow hides the one piece of information that matters, namely what causes the change. Keep event names short and verb-like (“submit”, “approve”, “expire”) so the arrows read as sentences.
Common gotchas
Omitting -v2 from the first line silently selects the older renderer, which draws clunkier arrows and handles some labels worse. State names are identifiers, so avoid spaces in them; single CamelCase words such as InReview keep both the parser and your readers happy. Every state name must be unique — reusing a name merges the states just as duplicate node ids merge flowchart nodes. Finally, remember that [*] is a marker, not a state: you cannot transition out of an end marker, and wanting to is a sign the diagram has another phase it should model explicitly.
Tips for mobile editing
One transition per line is the rule here even more than elsewhere, because transition lines are short and easy to tap accurately. Name states after what the thing is (“Published”) and events after what happens (“release”) — this discipline makes typos obvious, since a state name in the event position reads wrong immediately. Sketch the happy path first with three or four states, render it, then add failure and edge-case transitions one at a time. The cheatsheet fits the whole syntax on one screen.
State diagrams overlap with neighbors in useful ways: a flowchart is better when many actors make choices, while a sequence diagram is better when the interesting part is the messages exchanged rather than the modes of one thing.
State Diagram templates
Every template opens in the editor with the code pre-filled — edit it on your phone or desktop.
