State diagram

stateDiagram-v2
  [*] --> Idle
  Idle --> Working : start
  Working --> Idle : pause
  Working --> Done : finish
  Done --> [*]
  note right of Working : Can pause midway

timeline:
  enter Working slide-top, enter Idle-Working fade
  enter Working-Idle fade, highlight Working glow
  unhighlight Working, enter Done slide-bottom, enter Working-Done fade
  enter Done-end:1 fade

stateDiagram and stateDiagram-v2 are the same diagram.

States and transitions

  • Idle on a line of its own declares a state; a state named in a transition is also declared automatically. State ids may contain only letters, digits and _.
  • One line can hold several statements, as in Mermaid: a bare id ends at the whitespace after it, so Foo Bar declares two states and Foo Bar --> Done declares Foo plus the transition Bar --> Done.
  • Transition: A --> B; with a label, A --> B : label.
  • A transition to itself: A --> A.
  • [*] on the left of the arrow is a start, on the right an end. Each level (the whole document, each composite state) has only one start and one end. [*] on a line of its own is the level’s start; a later [*] --> A leaves from the same disc.
  • A transition ends on the figure it reaches: on the diamond of a <<choice>> and on the circle of a [*], not on the box around them.
  • Statement keywords are read in any case: CLASSDEF, STATE C {, Direction Rl and so on.

Descriptions

stateDiagram-v2
  state "Waiting" as Idle
  Idle : No work
  Idle --> Busy
  • Idle : description or state "description" as Idle. as does not change the id; the id is still Idle.
  • A description is drawn in place of the id. With two or more, the first becomes the title and the rest are listed below a divider.
  • A long description, quoted name or note wraps by itself once its text is wider than 175px, and a long transition label, drawn on the line over the theme’s --siren-edge-label-fill, once it is wider than 150px, as in Mermaid: at spaces, or between any two CJK characters, with closing punctuation never beginning a row. <br> breaks a row where you put it. A composite state’s title never wraps.

Reserved words

state, note, classDef, class, style, click, scale, href, default and stateDiagram (case-insensitive), the ten words Mermaid reserves, cannot be used as state names, nor as the subject of a description (note : hi); doing so reports an error. end, fork, choice, direction and the like are fine.

Composite states

stateDiagram-v2
  [*] --> Active
  state Active {
    [*] --> Loading
    Loading --> Ready
    Ready --> [*]
  }
  Active --> Closed
  • state name { … }, or state "description" as name { … }.
  • They can be nested, and each level has its own [*] start and end.
  • A transition can connect to the composite state itself.
  • The frame is filled with the theme’s --siren-subgraph-fill, none by default; see Themes.
  • It must span several lines; writing state X { A --> B } on one line reports an error.

Concurrent regions

Inside a composite state, a line containing only -- separates concurrent regions:

stateDiagram-v2
  state Running {
    [*] --> Audio
    --
    [*] --> Video
  }

-- may only appear inside a composite state.

Choice, fork, join

stateDiagram-v2
  state Check <<choice>>
  state Split <<fork>>
  state Merge <<join>>
  [*] --> Check
  Check --> Split : ok
  Check --> [*] : fail
  Split --> A
  Split --> B
  A --> Merge
  B --> Merge
  • <<choice>> is drawn as a diamond, <<fork>> and <<join>> as a thick bar, none of them with text.
  • The marker must be written on the line that first mentions the state; adding it later has no effect (as in Mermaid).
  • The [[fork]] syntax is not supported.

Note

  • note right of Idle : text, note left of Idle : text. The side is read in any case, and is drawn on the side you wrote: note LEFT OF X goes on the left, where Mermaid puts it on the right.
  • A multi-line note: note right of Idle on its own line, then the text, then end note. Each non-blank line is one row.
  • note right of [*] : text hangs on the level’s start; a level with no start reports an error, as Mermaid cannot draw it either.
  • Each state has at most one note; a later one replaces an earlier one.
  • A note’s connector meets the figure its state is drawn as: the disc of a [*], the diamond of a <<choice>>.
  • note "text" as N (a floating note) is accepted but not drawn, as in Mermaid.

Direction

direction TB, TD, BT, LR, RL. At the document level the first one wins. Inside a composite state or a concurrent region it affects only that level, and is given up as soon as a transition whose two ends have different parents passes through it: one end inside (at any depth) and one outside, or two of its own members at different nesting depths. Such a transition voids every composite state from each end up to and including the two ends’ nearest common one, and each is then laid out as its parent lays out its members: in the direction the enclosing composite state keeps, top to bottom when that one names none, or the document’s at the top level, as in Mermaid 12. A transition to the composite state itself from beside it, or from the composite state to itself, does not count. A composite state or concurrent region that names no direction is laid out top to bottom whatever the document’s direction, as in Mermaid. A note’s connector never makes a composite state give up its direction; Mermaid’s does.

Styles

stateDiagram-v2
  Idle --> Error
  classDef bad fill:#fee2e2,stroke:#dc2626
  class Error bad
  style Idle fill:#dbeafe,stroke:#2563eb
  • Define with classDef name property:value,... and apply with class A,B name. The rest of a class line is read as names one per word, as Mermaid paints them: class A c extra applies c, and class Busy a,b applies a class called a,b, which no classDef defines. A class no classDef defines is a warning: the state is drawn unstyled.
  • style A property:value,... writes the declarations straight onto the state, and style A,B ... onto each. A style beats a class applied to the same state whichever line comes first, as in Mermaid.
  • Composite states can be styled too; transitions cannot.
  • A timeline highlight always wins over an author’s stroke: while a state is highlighted, outline and glow draw its border in the highlight color, and give the author’s back afterwards.

Accessibility

accTitle: title, accDescr: description and the braced accDescr { ... } block are the diagram’s accessible title and description, in any case; the last one wins.

Timeline targets

Element id Example
State, composite state The state name (choice, fork and join too) Idle, Active
Start, end start:N, end:N, where N is the level number start:1, end:1
Concurrent region region:N, in source order region:1
Transition from-to, with #2 for a repeat; [*] uses its id Idle-Working, start:1-Idle, Done-end:1
  • Level numbers: the whole document is 1, then each composite state in order of first declaration, then their concurrent regions. A level that uses no [*] still takes a number.
  • A note has no id of its own; it animates together with the state it belongs to.

Not yet supported

Syntax Current behavior
A:::name No error, but ::name is drawn as a description; use class A name instead
note over X Error
hide empty description, click, scale Error