Mermaid State Diagram Guide: Model System Behavior with Code

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:

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : start
    Processing --> Done : complete
    Processing --> Error : fail
    Error --> Idle : retry
    Done --> [*]

Key syntax elements:

Modeling a Real-World Order Lifecycle

Here is a practical example — an e-commerce order state machine:

stateDiagram-v2
    [*] --> Created
    Created --> Paid : payment_received
    Created --> Cancelled : user_cancelled
    Paid --> Shipped : dispatch
    Paid --> Refunded : refund_requested
    Shipped --> Delivered : delivery_confirmed
    Delivered --> Completed : review_period_ended
    Cancelled --> [*]
    Refunded --> [*]
    Completed --> [*]

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:

stateDiagram-v2
    [*] --> Active
    
    state Active {
        [*] --> Listening
        Listening --> Processing : command_received
        Processing --> Listening : done
    }
    
    Active --> Suspended : pause
    Suspended --> Active : resume
    Active --> [*] : shutdown

Composite states keep large diagrams readable and map naturally to how developers think about system modules.

Concurrent States

Model parallel processes with fork/join:

stateDiagram-v2
    [*] --> Running
    
    state Running {
        [*] --> Heating
        [*] --> Agitating
        Heating --> [*]
        Agitating --> [*]
    }
    
    Running --> Complete
    Complete --> [*]

Best Practices

1. Name states with PascalCase: OrderShipped not os
2. Label transitions with past-tense events: payment_received, not pay
3. Keep diagrams under 15 states for readability
4. Use composite states to group related transitions
5. 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.