Vloam Mermaid

Docs

State diagrams

Model life cycles with states, events, and clear start and end markers.

Scroll to zoom · drag to pan

A state diagram shows how something changes over time. Each box is a state. Each arrow is an event that moves you to the next state.

Use the modern header

Start with:

stateDiagram-v2
  [*] --> Idle
  Idle --> Running : start
  Running --> Idle : stop
  Running --> [*] : exit

[*] is special:

  • [*] --> State — enter from the start
  • State --> [*] — leave to the end

Name the transition

Put the event after a colon:

Draft --> Review : submit

Readers should understand the event without reading your code. Prefer submit, approve, fail over long sentences.

Nest only when needed

You can group states when a phase has its own mini life cycle:

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

Nesting helps. Deep nesting hides the story. Prefer two flat diagrams over one nested maze.

Writing tips

  • Start from [*] and end at [*] so the life cycle feels complete.
  • Avoid duplicate paths that mean the same event.
  • If two states differ only by a flag, merge them and put the flag on the transition label.