State diagram
Capture every state and transition of a system
What is a State diagram?
A state diagram shows the states an object can be in and the events that move it between them: order lifecycles, document workflows, UI states, connection handling. Essential whenever “what state are we in?” matters.
State diagrams belong in specifications, where “can an order go from refunded back to shipped?” has to have an answer. They are the only diagram that makes illegal transitions visible: what is not drawn is not allowed, which turns the picture into a test plan. Their limit is combinatorics — two independent machines in one diagram produce a cross-product nobody can read. Split them, or nest them in composite states.
Live example
stateDiagram-v2
[*] --> Draft
Draft --> Review : submit
Review --> Draft : request changes
Review --> Approved : approve
Approved --> Published : publish
Published --> Archived : archive
Archived --> [*]When to use it
Common mistakes
Multi-word state names split apart
Waiting for payment --> Paid creates three states called Waiting, for and payment. Name the state once with state "Waiting for payment" as waiting, then use the short id waiting in every transition.
Nested [*] is not the start
A [*] written inside a composite state marks that composite’s entry point, not the diagram’s. If every [*] you wrote is nested, the diagram itself has no entry point and readers cannot tell where to begin.
Transition labels are events, not code
The text after the colon is free text: score > 80 is displayed but never evaluated, and two transitions can carry contradictory conditions without complaint. Review the labels the way you review prose, not the way you review logic.
Basic syntax
stateDiagram-v2
[*] --> Idle
Idle --> Active : start
Active --> [*] : stopstateDiagram-v2 direction LRUse the -v2 renderer, the one the current syntax is written for. Adding direction LR suits long linear lifecycles that would otherwise run off the bottom of the page.
[*] --> Draft Draft --> Review : submit[*] is the start marker on the left of an arrow and the final state on the right. The text after the colon names the event that triggers the transition.
state Payment { [*] --> Pending Pending --> Captured }A composite state hides a sub-machine behind one box. A transition can target the composite itself, which enters it through its own start marker.
state gate <<choice>> gate --> Approved : score > 80A choice pseudostate branches on a condition without inventing a fake state for it. The <<fork>> and <<join>> markers do the same for parallel paths.
Questions about this diagram
What is the difference with a flowchart?
A flowchart follows a process from start to finish. A state diagram describes all possible states of one thing and which events cause transitions — including cycles and error states.
Does Mermaid support nested states?
Yes — stateDiagram-v2 supports composite (nested) states, forks, joins, choices and notes for realistic state machines.
Can a Mermaid state diagram express guards, entry and exit actions?
Not formally. A transition carries one free-text label, so a guard like score > 80 is written there as prose and nothing enforces it. There is no entry or exit action syntax either — put those in a note beside the state.
How do I show a state that loops back to itself?
Put the same state on both sides of the arrow: Draft --> Draft : edit. Mermaid draws it as a loop on the box and keeps the label, and several transitions between the same two states each keep their own label instead of merging.
Can I colour one state differently?
Yes. classDef bad fill:#fdd defines a style and class Failed bad applies it, so error or terminal states stand out. The styling lives in the source, so it survives export to PNG and SVG.
How do I export a state diagram for a slide deck?
Export PNG at 2× or 4× for slides that will be projected, or SVG when the tool accepts it, since SVG stays sharp and keeps the text selectable. The Mermaid source remains the version you edit and re-export.
State diagram or another diagram type?
State diagram or sequence diagram?
A sequence diagram shows one path through several participants; a state diagram shows every path through one participant. If the interesting question is “what did the API answer”, use a sequence diagram. If it is “can we ever get back here”, use states.
State diagram or class diagram?
The class diagram gives an Order its fields and relations; the state diagram gives it a life. Write the class diagram when people ask what data exists, and the state diagram when they ask which transitions the code has to reject.
Create your State diagram now
Describe it in plain language — the AI writes the Mermaid code for you.
Open Mermaid Studio