stateDiagram-v2v0.9.4
What is a State diagram?
State machines, transitions, lifecycles.
stateDiagram-v2
When to use it
Use a State when…
01
Finite state machines for UI components
02
Order/document lifecycles
03
Protocol transitions (TCP, OAuth)
Syntax basics
The minimal syntax
Copy this and you have a working state. Build from here.
state.mmd
stateDiagram-v2
[*] --> Draft
Draft --> Review : submit
Review --> Approved : lgtm
Review --> Draft : changes requested
Approved --> Published : publish
Published --> [*]Common patterns
Patterns worth memorizing
Composite states
Nest states inside a parent with `state Parent { … }` for hierarchical machines.
Forks/joins
Use `<<fork>>` and `<<join>>` to model concurrent transitions.
Transition guards
`A --> B: event [guard]` is rendered as a single label; keep guards short.
Common gotchas
The things that will trip you up
Mermaid silently ignores misspellings — these are the failures we see most.
- 01
Use `stateDiagram-v2` — the original `stateDiagram` is legacy and lacks composite-state support.
- 02
`[*]` is the start/end state, not a literal node.
- 03
Transition labels with colons: anything after the first `:` is the label, so don't put extra colons.
Related diagram types