Mermaid state diagrams
A Mermaid state diagram models a state machine as text: the states something can be in, and the events that move it between them. If your code has a `status` column or an enum, a state diagram is its documentation.
An order lifecycle with a cancellation path.
State diagrams catch bugs before they ship — drawing the lifecycle of an order or subscription exposes the transitions nobody handled. Keep the diagram next to the code and update both in the same pull request.
When to use a state diagram
- Order, subscription, and ticket lifecycles
- Specifying UI states (loading, success, error, retry)
- Workflow engines and approval chains
- Modelling protocol or connection states
The Mermaid code
Copy it anywhere Mermaid renders — or see the full syntax reference.
stateDiagram-v2
[*] --> Pending
Pending --> Paid : payment captured
Pending --> Cancelled : timeout / user cancels
Paid --> Shipped : fulfilment
Shipped --> Delivered : carrier scan
Delivered --> Refunded : return accepted
Cancelled --> [*]
Refunded --> [*]
Delivered --> [*]Frequently asked questions
- How do I create a state diagram in Mermaid?
- Start with `stateDiagram-v2`. `[*]` is the start (and end) marker, and each transition is one line: `Pending --> Paid : payment captured`, where the text after the colon names the triggering event. States can nest by declaring `state Name { … }` blocks.
- What's the difference between stateDiagram and stateDiagram-v2?
- `stateDiagram-v2` is the current renderer with better layout, nested states, and notes; the original `stateDiagram` is kept for backwards compatibility. Use v2 for all new diagrams.
- Can AI draft the state machine for me?
- Yes. Tell MermaidCreator's AI what the entity is and how it behaves — 'a support ticket that can be open, pending customer, resolved, or reopened' — and it drafts states and labelled transitions you can refine.