Mermaid state diagram syntax: states, transitions and choices with examples

A state diagram models one object's life: the states it can be in, and the events that move it between them. Mermaid's stateDiagram-v2 is the version to use — the older stateDiagram keyword is accepted for compatibility but -v2 is what the current docs document.

Everything on this page is rendered by makesPDF's own Mermaid renderer, so a ```mermaid block produces exactly this in the PDF.

States and transitions

[*] is the start marker and the end marker — the same symbol, told apart by which side of the arrow it sits on. Everything else is a state, declared implicitly the first time it appears:

stateDiagram-v2
  [*] --> Draft
  Draft --> Review : Submit
  Review --> Approved : Approve
  Review --> Draft : Request Changes
  Approved --> [*]

The text after the colon is the transition label. A transition without one is valid too: Draft --> Review.

Long labels

state "Waiting for approval" as Waiting gives a state an id and a separate display label, so a transition can name the id while the diagram shows the sentence:

stateDiagram-v2
  state "Waiting for review" as Waiting
  [*] --> Waiting
  Waiting --> Published : Approve
  Waiting --> Draft : Request changes
  Published --> [*]

Direction

direction LR on its own line after the header lays the diagram out left to right instead of top down — worth it for a long linear flow that otherwise runs down the page:

stateDiagram-v2
  direction LR
  [*] --> Draft
  Draft --> Review : Submit
  Review --> Approved : Approve
  Approved --> [*]

Fork, join and choice

<<fork>> and <<join>> draw the thick bars used for parallel work, and <<choice>> draws the diamond used for a decision that is resolved by the guard. Transitions out of a choice are labelled with their conditions:

stateDiagram-v2
  [*] --> Fork
  state Fork <<fork>>
  state Join <<join>>
  Fork --> Charge
  Fork --> Notify
  Charge --> Join
  Notify --> Join
  Join --> Check
  state Check <<choice>>
  Check --> Done : card ok
  Check --> Failed : declined
  Done --> [*]
  Failed --> [*]

Composite states and notes

Mermaid also lets a state contain a diagram of its own — state Editing { [*] --> Typing } — and attaches annotations with note right of Sending: …. Both are parsed, and worth knowing about when you read someone else's diagram, but neither draws correctly here yet — see the note below.

Not supported in makesPDF yet: a composite state's frame is drawn, but the states inside it lose their labels, so a nested diagram is unreadable — flatten the states for now. note annotations are drawn outside the SVG canvas and are therefore invisible, and state-level styling (classDef, class) is parsed but not painted. A <<fork>> or <<join>> bar and a <<choice>> diamond are drawn without their state name, so a fork and a join look alike — read them from the transitions.