Mermaid State Diagram: state machines, transitions, and concurrent states

Mermaid’s State Diagram lets you describe state machines in plain text — faster than Visio, more precise than Flowchart for describing entity lifecycles. Ideal for: order status, user lifecycle, approval workflows, protocol states.

Why State Diagram over Flowchart

Flowchart describes a process — what steps happen in what order. State Diagram describes states — what condition an entity is in at any given moment, and under what conditions it transitions to another state.

Use cases:

• Order systems: Pending → Paid → Shipped → Delivered (each state is a snapshot of the entity)
• Approval flows: Draft → Submitted → Under Review → Approved/Rejected
• Network protocols: Handshake → Connected → Transferring → Disconnected
• User lifecycle: Registered → Activated → Active → Dormant → Cancelled

Minimal Example

1
2
3
4
5
6

stateDiagram-v2
    [*] --> Pending
    Pending --> Paid: payment success
    Paid --> Shipped: merchant ships
    Shipped --> Delivered: confirm receipt
    Delivered --> [*]

• [*] is the special start/end state
• stateDiagram-v2 is the current recommended syntax (richer than plain stateDiagram)
• --> is a state transition; event[condition] suffix is optional

Two Syntaxes: stateDiagram vs stateDiagram-v2

Always use stateDiagram-v2.

State Declaration

Inline vs full syntax

1

state "Display Name" as stateID

Full syntax with description:

1

state stateID: description line 1\nline 2

Anonymous states — write text directly, Mermaid auto-generates an ID:

1

[*] --> Pending

Transitions

Basic arrows

1
2
3
4
5
6
7
8

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted: submit
    Submitted --> UnderReview: review
    UnderReview --> Approved: approve
    UnderReview --> Rejected: reject
    Approved --> [*]
    Rejected --> Draft: revise

Transitions with conditions and events

1

StateA --> StateB: event[condition]

1
2
3
4
5

stateDiagram-v2
    [*] --> Active
    Active --> Dormant: inactive[>30 days]
    Dormant --> Active: login
    Dormant --> Cancelled: expire[>180 days]

Choice / branches

1
2
3
4
5
6
7

stateDiagram-v2
    [*] --> Payment
    Payment --> Decision: callback
    Decision --> Success: amount > 0
    Decision --> Failure: amount <= 0
    Success --> [*]
    Failure --> [*]

Nested States (Composite State)

1
2
3
4
5
6
7
8
9
10
11

stateDiagram-v2
    [*] --> LoggingIn
    LoggingIn --> LoggedIn: auth success
    LoggedIn --> LogOut: logout
    
    state LoggingIn {
        [*] --> EnterPassword
        EnterPassword --> Verifying: submit
        Verifying --> EnterPassword: retry
        Verifying --> LoggedIn: success
    }

Nested states express “this state internally has substates”. Maximum 3 levels — beyond that rendering breaks.

Concurrent States (Orthogonal Regions)

|| separates parallel, independent state regions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

stateDiagram-v2
    [*] --> TaskInProgress
    
    state "TaskInProgress" as Task {
        [*] --> Development
        Development --> Testing: dev done
        Testing --> Deployed: test passed
        
        --
        
        [*] --> Documentation
        Documentation --> DocDone: doc done
    }
    
    TaskInProgress --> [*]: all complete

-- creates parallel regions within a parent state. Development and Documentation happen concurrently.

Entry and Exit Actions

1
2
3
4
5
6
7
8
9
10
11
12
13

stateDiagram-v2
    [*] --> Init
    Init --> Ready: init complete
    
    state Ready {
        [*] --> Idle
        Idle --> Processing: job received
        Processing --> Idle: job complete
        
        Idle : entry/ log('entering idle')
        Processing : entry/ log('processing started')
        Processing : exit/ log('processing done')
    }

entry/ and exit/ declare actions that fire when entering/exiting a state.

Styling

Per-state color

1
2
3
4
5
6
7
8

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing
    Processing --> Done
    
    style Pending fill:#f9f,stroke:#333
    style Processing fill:#ff6b6b,stroke:#333
    style Done fill:#6bcb77,stroke:#333

Style classes (reusable)

1
2
3
4
5
6
7

stateDiagram-v2
    [*] --> A
    A --> B
    B --> [*]
    
    classDef errorState fill:#ff6b6b,stroke:#333
    class B errorState

Theme

1
2
3
4
5

%%{init: {'theme': 'dark'}}%%
stateDiagram-v2
    [*] --> Active
    Active --> Dormant: sleep
    Dormant --> Active: wake

Mermaid vs PlantUML State Diagram

Both are functionally equivalent. Choose Mermaid for readability, PlantUML for strict UML compliance.

Common Errors

Recap

5 things to remember:

1. Always use stateDiagram-v2 (plain stateDiagram is incomplete)
2. [*] is the start/end marker
3. --> target: event[condition] is the transition syntax
4. Nested states with state parent { child states } express composite states
5. || separates concurrent state regions for parallel independent flows

State diagrams describe entity lifecycle — orders, approvals, users, sessions, devices — use them whenever you need to show what state something is in and what triggers transitions.