MermanDraw
Open Editor

Mermaid guide

Mermaid Sequence Diagram Syntax: Participants, Messages, Loops, and Notes

A sequence diagram shows who talks to whom, in what order. Mermaid lays out participants left to right and draws time flowing downward, one message per line. It is the standard way to document an API call chain, an authentication handshake, or any request that crosses more than one service.

Each message line has the shape A->>B: text. The arrow token decides line style and arrowhead; the colon separates the message text. Everything else, from loops to notes, is a block keyword that wraps a group of message lines.

  • API request and response flows
  • auth handshakes
  • distributed system traces
  • protocol explanations

Example

Mermaid Sequence Diagram exampleDBAPIEditorUserDBAPIEditorUserPaste Mermaid codeRender diagram (300ms debounce)Click SharePOST /api/diagramsINSERT diagramid{ id }Share link copied!
sequenceDiagram
    participant User
    participant Editor
    participant API
    participant DB
    User->>Editor: Paste Mermaid code
    Editor->>Editor: Render diagram (300ms debounce)
    User->>Editor: Click Share
    Editor->>API: POST /api/diagrams
    API->>DB: INSERT diagram
    DB-->>API: id
    API-->>Editor: { id }
    Editor-->>User: Share link copied!
Open in editor → Cheatsheet →

Syntax

Participants and actors

sequenceDiagram
    actor User
    participant App
    participant API as Backend API
    User->>App: Tap "Sign in"
    App->>API: POST /session
Participants and actors — Mermaid sequenceBackend APIAppBackend APIAppUserTap "Sign in"POST /sessionUser

Participants appear in declaration order. as sets a display name so the alias can stay short in message lines. actor draws a stick figure.

Try this snippet →

Arrow types

sequenceDiagram
    A->B: solid line, no head
    A-->B: dotted line, no head
    A->>B: solid line, arrowhead
    A-->>B: dotted line, arrowhead (reply)
    A-xB: solid line, cross (lost)
    A-)B: solid line, open arrow (async)
Arrow types — Mermaid sequenceBABAsolid line, no headdotted line, no headsolid line, arrowheaddotted line, arrowhead (reply)solid line, cross (lost)solid line, open arrow (async)

Convention: ->> for a call, -->> for its response. Mixing them consistently is what makes a diagram readable.

Try this snippet →

Activation bars

sequenceDiagram
    Client->>+Server: request
    Server-->>-Client: response
Activation bars — Mermaid sequenceServerClientServerClientrequestresponse

+ after the arrow activates the target, - deactivates. Or write activate Server / deactivate Server on their own lines.

Try this snippet →

Control blocks

sequenceDiagram
    loop every 30s
        App->>API: heartbeat
    end
    alt token valid
        API-->>App: 200 OK
    else expired
        API-->>App: 401
    end
    par fetch in parallel
        App->>CDN: GET /assets
    and
        App->>API: GET /me
    end
    opt cache warm
        App->>App: skip fetch
    end
Control blocks — Mermaid sequenceCDNAPIAppCDNAPIApploop[every 30s]alt[token valid][expired]par[fetch in parallel]opt[cachewarm]heartbeat200 OK401GET /assetsGET /meskip fetch
Try this snippet →

Notes and numbering

sequenceDiagram
    autonumber
    Note over App,API: Both sides validate the token
    App->>API: GET /me
    Note right of API: Cached for 60s
Notes and numbering — Mermaid sequenceAPIAppAPIAppBoth sides validate the tokenCached for 60sGET /me1

autonumber prefixes every message with a sequence number, which is handy when a document references steps by number.

Try this snippet →

Common mistakes

These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.

  • Missing colon: User->>App Tap button.

    Fix: Every message needs : text after the target, even if the text is empty-ish. Write User->>App: Tap button.

  • Flowchart arrows (--> with a target in brackets) inside a sequence diagram.

    Fix: Sequence arrows are ->>, -->>, ->, -->. Brackets are not shapes here; they will be read as part of the participant name.

  • Participant names with spaces or slashes used directly: Auth Service->>DB: query.

    Fix: Declare an alias: participant AS as Auth Service, then use AS->>DB: query.

  • Unbalanced blocks: an alt without end, or an else outside an alt.

    Fix: Every loop, alt, opt, par, critical, and rect needs its own end. Indent blocks so the pairing is visible.

Real-world examples

Complete, copy-ready sequence diagrams for common situations. Each one opens in the editor with a click.

Browse all examples →

FAQ

How do I show a message a participant sends to itself?

Use the same name on both sides: App->>App: validate input. Mermaid draws a loop-back arrow on that lifeline.

Can I change the order participants appear in?

Yes. Participants are placed in the order they are first mentioned, so declare them explicitly at the top in the order you want.

Is there a limit on diagram width?

No hard limit, but more than seven or eight participants becomes hard to read. Split by concern (auth, payment, notification) into separate diagrams and share each one with its own link.