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
Header
stateDiagram and stateDiagram-v2 are the same diagram.
States and transitions
Idleon 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 Bardeclares two states andFoo Bar --> DonedeclaresFooplus the transitionBar --> 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[*] --> Aleaves 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 Rland so on.
Descriptions
stateDiagram-v2
state "Waiting" as Idle
Idle : No work
Idle --> Busy
Idle : descriptionorstate "description" as Idle.asdoes not change the id; the id is stillIdle.- 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 {…}, orstate "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,noneby 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 Xgoes on the left, where Mermaid puts it on the right.- A multi-line note:
note right of Idleon its own line, then the text, thenend note. Each non-blank line is one row. note right of [*] : texthangs 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 withclass A,B name. The rest of aclassline is read as names one per word, as Mermaid paints them:class A c extraappliesc, andclass Busy a,bapplies a class calleda,b, which noclassDefdefines. A class noclassDefdefines is a warning: the state is drawn unstyled. style A property:value,...writes the declarations straight onto the state, andstyle A,B ...onto each. Astylebeats a class applied to the same state whichever line comes first, as in Mermaid.- Composite states can be styled too; transitions cannot.
- A timeline
highlightalways wins over an author’sstroke: while a state is highlighted,outlineandglowdraw 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 |