Markdown state diagram maker

Model a state machine as a diagram. Describe the states and transitions in Mermaid to document workflows, UI states or protocol behaviour.

Mermaid state syntax

A state diagram is a set of states and the transitions between them. You name the states and draw an arrow for each transition, with an optional label for what triggers it. Here is each piece you can write.

States and transitions

Draw a transition from one state to another with an arrow. Any name you use becomes a state.

You write

stateDiagram-v2
  Idle --> Running
  Running --> Idle

You get

Start and end

The marker [*] is the start point when it is on the left of an arrow, and the end point when it is on the right.

You write

stateDiagram-v2
  [*] --> Idle
  Idle --> [*]

You get

Transition labels

Add a colon and text after a transition to say what triggers it.

You write

stateDiagram-v2
  Idle --> Running : start
  Running --> Idle : stop

You get

Direction

Set which way the diagram flows. TB is top to bottom, LR is left to right.

You write

stateDiagram-v2
  direction LR
  [*] --> A
  A --> B
  B --> [*]

You get

Composite states

Wrap states in state Name { ... } to nest a machine inside a state.

You write

stateDiagram-v2
  [*] --> Active
  state Active {
    [*] --> Idle
    Idle --> Busy : work
    Busy --> Idle : done
  }
  Active --> [*]

You get

Notes

Attach a note to a state with note left of or note right of.

You write

stateDiagram-v2
  [*] --> Idle
  Idle --> Running : start
  note right of Idle : waiting for input

You get

Cheat sheet

Write this	You get
`A --> B`	Transition from state A to state B
`A --> B : label`	Transition with a trigger label
`[*] --> A`	A is the start state
`A --> [*]`	A is an end state
`A : Description`	Give state A a longer label
`direction LR`	Lay the diagram out left to right
`state A { ... }`	A composite state with its own inner states
`note right of A : text`	Attach a note to a state