State Diagram

Use Mermaid stateDiagram-v2 to show how something moves between states based on events or conditions.

Basic template

stateDiagram-v2
    [*] --> Draft
    Draft --> Published
    Published --> [*]

Core syntax

• Start with stateDiagram-v2
• Use [*] for start or end
• Define transitions with StateA --> StateB
• Add labels with StateA --> StateB : event
• Nest states with state Name { ... }

Common example

stateDiagram-v2
    [*] --> New
    New --> Validating : submit
    Validating --> Approved : checks pass
    Validating --> Rejected : checks fail
    Approved --> Archived : complete
    Rejected --> New : revise
    Archived --> [*]

Good for

• Workflow states
• Lifecycle documentation
• Approval and review processes

Watch for

• State diagrams are about status transitions, not who performs the work
• If actor interactions matter, pair with a sequence diagram