Example
stateDiagram-v2
[*] --> Idle
Idle --> Editing : user types
Editing --> Rendering : debounce 300ms
Rendering --> Rendered : success
Rendering --> Error : parse fail
Error --> Editing : user fixes
Rendered --> Sharing : click Share
Sharing --> Shared : API ok
Shared --> [*]Syntax
States and transitions
stateDiagram-v2
[*] --> Draft
Draft --> Review : submit
Review --> Draft : request changes
Review --> Published : approve
Published --> [*]Transition text after the colon is the event or guard. State names with spaces need an alias: state "In Review" as Review.
Composite states
stateDiagram-v2
[*] --> Active
state Active {
[*] --> Idle
Idle --> Running : start
Running --> Idle : stop
}
Active --> Stopped : shutdownA composite state has its own start marker and internal transitions. Nest as deep as needed.
Try this snippet →Choice, fork, and join
stateDiagram-v2
state check <<choice>>
state fork <<fork>>
state join <<join>>
[*] --> check
check --> Small : size < 1MB
check --> Large : size >= 1MB
Large --> fork
fork --> Compress
fork --> Scan
Compress --> join
Scan --> join
join --> [*]Concurrency and notes
stateDiagram-v2
state Player {
[*] --> Playing
--
[*] --> Unmuted
Unmuted --> Muted : mute
}
note right of Player : two regions run in parallelA line with -- inside a composite state splits it into concurrent regions.
Common mistakes
These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.
-
Using
stateDiagram(v1) and getting different rendering or missing features.Fix: Always write
stateDiagram-v2. The v1 renderer is kept only for backward compatibility. -
State names with spaces used directly:
In Review --> Published.Fix: Declare an alias first:
state "In Review" as InReview, then useInReview. -
Transition label with a colon in it (
Review --> Done : approve: final).Fix: Only the first colon splits label from transition. Avoid additional colons or rephrase.
Real-world examples
Complete, copy-ready state diagrams for common situations. Each one opens in the editor with a click.
-
User Session Lifecycle State Diagram with Idle and Expiry
Mermaid state diagram of a login session: anonymous, authenticating, an Active composite state with working, idle, and locked substates, then expiry or logout.
-
Customer Support Ticket Lifecycle State Diagram
A Mermaid state diagram for a help desk ticket: new, triaged, in progress, waiting on customer, resolved, closed, plus the reopen path and auto-close rule.
-
SaaS Subscription Lifecycle State Diagram
A Mermaid state diagram of a subscription from trial to active, past due, and canceled, with the retry grace period and the reactivation window billing handles.
-
Mobile App Screen Navigation Flow State Diagram
A Mermaid state diagram with each mobile screen as a state: splash, onboarding, sign-in, home, search, detail, checkout, confirmation, and back edges.
FAQ
How do I set the layout direction?
Add direction LR on the line after stateDiagram-v2. Composite states can set their own direction inside the braces.
Can I style a particular state?
Yes. classDef danger fill:#fee2e2,stroke:#dc2626 then class Error danger. Or pick a theme in MermanDraw to restyle everything consistently.