Learn
State diagram syntax
Learn stateDiagram-v2, start/end markers, labeled transitions, notes, and nested states for the Diagram lifecycle template.
On this page9 sections
Syntax cheatsheet
Quick reference for this diagram type
| Concept | Syntax |
|---|---|
| Declare | stateDiagram-v2 |
| Start / end | [*] --> State · State --> [*] |
| Transition | Draft --> Editing |
| Labeled transition | Draft --> Editing : edit |
| Note | note right of Draft: text |
| Composite | state Parent { … } |
- 1
Declare stateDiagram-v2
Prefer stateDiagram-v2 for modern state charts. States are identifiers; arrows define transitions between them.
Name states with clear product language (Draft, Shared) so the diagram doubles as documentation.
stateDiagram-v2 Draft --> Editing Editing --> Shared
Expand - 2
Start and end with [*]
[*] is the special start/end marker. [*] --> State enters the machine; State --> [*] leaves it.
A diagram can have multiple paths to [*], such as archiving from different states.
stateDiagram-v2 [*] --> Draft Draft --> Archived Archived --> [*]
Expand - 3
Transitions and labels
Connect states with -->. Add a label after a colon to name the event or action that causes the change.
Cycles are normal: Editing --> Draft models “save as draft again.”
stateDiagram-v2 Draft --> Editing : open Editing --> Draft : save Editing --> Shared : publish
Expand - 4
Notes on states
Attach notes left or right of a state to explain rules without cluttering transition labels.
stateDiagram-v2 [*] --> Draft note right of Draft: Not visible publicly Draft --> Shared : publish note left of Shared: Anyone with the link
Expand - 5
Composite (nested) states
Group related states inside state Name { … }. Nested machines keep large lifecycles readable.
Transitions can still target nested states or the composite as a whole, depending on how you model the product.
stateDiagram-v2 [*] --> Active state Active { [*] --> Draft Draft --> Editing Editing --> Draft } Active --> Archived Archived --> [*]Expand - 6
Choices in the flow
When a state can branch on a condition, model it with explicit transitions and clear labels rather than hiding logic in notes.
Keep the number of outbound arrows small so the chart stays understandable.
stateDiagram-v2 Editing --> Shared : publish Editing --> Draft : discard Shared --> Editing : revise Shared --> Archived : archive
Expand - 7
Put it together: Diagram lifecycle
Assemble start, editing loops, sharing, and archive into the lifecycle from the examples template.
stateDiagram-v2 [*] --> Draft Draft --> Editing Editing --> Draft Editing --> Shared Shared --> Editing Shared --> Archived Archived --> [*]
Expand
Check your level
80% or higher certifies this lesson. You'll get 3–5 random questions from a larger bank.