What a Mermaid state diagram is for
A state diagram (state machine) shows the states something can be in and the events that move it between them. It fits order lifecycles, connection handling, UI flows and anything modeled as a finite state machine.
State Diagram syntax
| Syntax | Meaning |
|---|---|
stateDiagram-v2 |
Use v2; it renders better than the original stateDiagram |
[*] --> A |
Start state |
A --> [*] |
End state |
A --> B: event |
Transition with a label |
state "Long name" as A |
State with a description |
state A { … } |
Composite state with nested states |
state fork <<fork>> / <<join>> |
Fork and join for parallel paths |
state check <<choice>> |
Choice point (a decision) |
-- |
Concurrency separator inside a composite state |
note right of A … end note |
Note |
direction LR |
Lay the diagram out left to right |
Basic example
stateDiagram-v2
[*] --> Pending
Pending --> Paid: payment received
Pending --> Cancelled: timeout
Paid --> Shipped: dispatch
Shipped --> Delivered: signed for
Delivered --> [*]
Cancelled --> [*]Open this example in the Mermaid editor
More state diagram examples
TCP-style connection with a choice
A <<choice>> node branches on a condition; composite states group the connected substates.
stateDiagram-v2
direction LR
[*] --> Idle
Idle --> Connecting: connect()
Connecting --> result
state result <<choice>>
result --> Connected: handshake ok
result --> Backoff: error
Backoff --> Connecting: retry timer
state Connected {
[*] --> Active
Active --> Draining: close()
Draining --> [*]
}
Connected --> Idle: closedOpen “TCP-style connection with a choice” in the editor
Parallel states with fork and join
fork splits into paths that run at the same time; join waits for all of them.
stateDiagram-v2
state fork_state <<fork>>
state join_state <<join>>
[*] --> Received
Received --> fork_state
fork_state --> ChargeCard
fork_state --> ReserveStock
ChargeCard --> join_state
ReserveStock --> join_state
join_state --> Confirmed
Confirmed --> [*]Open “Parallel states with fork and join” in the editor
Common mistakes
- State ids can’t contain spaces. Use state "Waiting for payment" as Waiting and refer to Waiting afterwards.
- Each composite state has its own [*] start and end, separate from the outer diagram’s.
Use it in Markdown
```mermaid
stateDiagram-v2
[*] --> Pending
Pending --> Paid: payment received
Pending --> Cancelled: timeout
Paid --> Shipped: dispatch
Shipped --> Delivered: signed for
Delivered --> [*]
Cancelled --> [*]
```GitHub, GitLab, Azure DevOps, Obsidian, Notion and docs generators such as Docusaurus and MkDocs (with a plugin) draw fenced mermaid blocks. Check it locally in the Markdown preview.
Other Mermaid diagrams
- Mermaid flowchart syntax
- Mermaid sequence diagram syntax
- Mermaid class diagram syntax
- Mermaid er diagram syntax
- Mermaid gantt chart syntax
- Mermaid pie chart syntax
- Mermaid mindmap syntax
- Mermaid timeline syntax
- Mermaid git graph syntax
- Mermaid user journey syntax
- Mermaid quadrant chart syntax
- Mermaid xy chart syntax
Sources
Spotted a mistake? Email hello@devtoolsmith.com and we’ll fix it.
Frequently asked questions
How do I start a Mermaid state diagram?
Begin the diagram with the keyword stateDiagram-v2 on its own line, then add one statement per line. In Markdown, wrap the whole diagram in a fenced code block with the language mermaid so GitHub, GitLab and most docs sites draw it.
How do I export a Mermaid state diagram as an image?
Paste the diagram into the editor on this page and use SVG or PNG above the preview. SVG stays sharp at any size and can be edited further; PNG is exported at twice the screen resolution for slides and documents. Nothing is uploaded.