State Diagram
A state diagram describes the behaviour of a system: the states it can be in, and the transitions that move it from one state to another. kymo's editor reads the MermaidstateDiagram-v2 syntax.
This page works like a quickstart: as you scroll, the pane on the right shows the source and the preview for the section you're reading. Copy grabs the source; ▶ Open in editor loads it into editor.kymo.studio (pick mermaid in the diagram-type dropdown when starting from scratch).
The example on the right models a moving object: [*] is both the start and the end state, and each --> is a transition.
stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
States and transitions
A bare identifier declares a state. Give it a human-readable description with a colon (s1 : description) or the state "description" as s1 form. A transition is from --> to, with an optional : label describing what triggers it.
direction LR (or TB, BT, RL) sets the flow of the layout.
stateDiagram-v2
direction LR
s1 : This is a state description
state "Also a description" as s2
s1 --> s2 : transition label
Composite states
A state can contain its own sub-state machine: state Name { … }. Composite states nest, and the inner machine has its own [*] start state. Transitions may connect composite states to outside states — but not a state inside one composite to a state inside another.
stateDiagram-v2
[*] --> Active
state Active {
[*] --> Idle
Idle --> Running : start
Running --> Idle : stop
}
Active --> [*] : shutdown
Choice, fork and join
state name <<choice>> declares a diamond that branches on a condition. <<fork>> splits a transition into parallel paths and <<join>> brings them back together.
stateDiagram-v2
state check <<choice>>
state fork1 <<fork>>
state join1 <<join>>
[*] --> check
check --> Small : if n < 10
check --> Big : if n >= 10
Big --> fork1
fork1 --> A
fork1 --> B
A --> join1
B --> join1
join1 --> [*]
Small --> [*]
Concurrency
Inside a composite state, a -- line splits the body into regions that run in parallel — the example shows the classic keyboard NumLock/CapsLock pair.
stateDiagram-v2
[*] --> Active
state Active {
NumLockOff --> NumLockOn : EvNumLockPressed
NumLockOn --> NumLockOff : EvNumLockPressed
--
CapsLockOff --> CapsLockOn : EvCapsLockPressed
CapsLockOn --> CapsLockOff : EvCapsLockPressed
}
Notes
Attach commentary with note right of X … end note (or left of), or the single-line form note left of X : text.
stateDiagram-v2
State1 : The state with a note
note right of State1
Important information!
end note
State1 --> State2
note left of State2 : This is the note to the left.
Status. State diagram previews on this page and in the editor use the Mermaid renderer; importing state diagrams into kymo's own pipeline (native SVG/PNG/PDF rendering) is on the roadmap.
See also
- Flowchart — for processes where the steps are actions rather than states.
- Class Diagram — the structural counterpart in UML modelling.