Skip to content
MermaidViewer
Log inOpen editor

Mermaid Sequence Diagram Tutorial: From Basics to Advanced

Learn Mermaid sequence diagrams step by step: participants, message types, activations, notes, loops, alt/else, parallel blocks, grouping boxes and numbering.

8 min readUpdated

Sequence diagrams explain interactions over time. This tutorial builds a realistic checkout flow step by step, introducing each Mermaid feature as you need it. Full syntax lives on the sequence diagram reference.

Participants and messages

mermaid
sequenceDiagram
    participant B as Browser
    participant S as Shop API
    B->>S: POST /checkout
    S-->>B: 201 Created

Declaring participants sets their order and lets you use short aliases. ->> is a request and -->> a response.

Activations

Activation bars show when a participant is busy. Add + to activate on a message and - to deactivate.

mermaid
sequenceDiagram
    participant B as Browser
    participant S as Shop API
    participant P as Payments
    B->>+S: POST /checkout
    S->>+P: Charge card
    P-->>-S: Charged
    S-->>-B: Order confirmed

Alternatives and loops

mermaid
sequenceDiagram
    participant S as Shop API
    participant P as Payments
    S->>P: Charge card
    alt success
        P-->>S: OK
    else declined
        P-->>S: Declined
        loop up to 3 times
            S->>P: Retry
        end
    end

Notes, boxes and numbering

mermaid
sequenceDiagram
    autonumber
    box Frontend
      participant B as Browser
    end
    box Backend
      participant S as API
      participant D as DB
    end
    B->>S: Request
    Note right of S: Validate input
    S->>D: Query
    D-->>S: Rows
    S-->>B: JSON

Best practices

  • Keep each diagram focused on one scenario; create separate diagrams for edge cases.
  • Use consistent verbs for messages (GET /x, Charge card, Emit event).
  • Number messages with autonumber when the diagram will be discussed.
  • Prefer notes over long message labels.