State diagrams visualize how a system moves between different states in response to events. They are essential for modeling user interfaces, order lifecycles, authentication flows, and any process with defined states and transitions.
Mermaid state diagrams let you define these models as text code — version-controllable, AI-friendly, and instantly renderable. This guide covers syntax from basic states to composite states and concurrent regions.
Basic State Diagram Syntax
Every Mermaid state diagram starts with the stateDiagram-v2 declaration:
Key syntax elements:
| Element | Syntax | Example |
|---|---|---|
| Start state | [*] | [*] --> FirstState |
| End state | [*] | LastState --> [*] |
| Transition | --> | StateA --> StateB : event |
| Transition label | : label | Idle --> Active : login |
| State description | state "label" | state "Waiting for input" as Wait |
Modeling a Real-World Order Lifecycle
Here is a practical example — an e-commerce order state machine:
This diagram is immediately useful in product documentation, API specs, and AI agent system prompts.
Composite and Nested States
For complex systems, group related states:
Composite states keep large diagrams readable and map naturally to how developers think about system modules.
Concurrent States
Model parallel processes with fork/join:
Best Practices
- Name states with PascalCase:
OrderShippednotos - Label transitions with past-tense events:
payment_received, notpay - Keep diagrams under 15 states for readability
- Use composite states to group related transitions
- Validate in Mermaid2Img before embedding in documentation
Export Your State Diagram
After writing your state diagram, paste it into Mermaid2Img to preview and export as PNG, SVG, or PDF for your documentation, presentations, or AI context files.
Frequently Asked Questions
What is the difference between a state diagram and a flowchart?
Flowcharts show process steps and decisions. State diagrams show how an entity moves between defined states in response to events. Use state diagrams when the focus is on what state something is in, not what step comes next.
Can I use state diagrams in GitHub README?
Yes. GitHub natively renders Mermaid state diagrams in markdown code blocks.
How do I share a state diagram as an image?
Use Mermaid2Img to export your diagram as PNG or SVG — no installation required, all processing happens in your browser.