Free · No sign-up · Works with .mmd files

Mermaid sequence diagram editor

A sequence diagram shows messages between participants in the order they happen, with time running down the page. Use one when the question is who calls whom, in what order, and what comes back — API handshakes, auth flows, retries. If the interesting part is branching logic inside one component, a flowchart fits better.

Open this in the editor →Read the guide

OAuth 2.0 authorisation code flow

The canonical case for a sequence diagram: four participants, a redirect the user cannot see, and a token exchange that must happen server-to-server. Prose describes this badly and a flowchart cannot show the ordering at all.

sequenceDiagram
    autonumber
    participant U as User
    participant B as Browser
    participant A as Auth server
    participant API as Resource API

    U->>B: Click "Sign in"
    B->>A: GET /authorize?client_id&redirect_uri
    A-->>B: Redirect to login page
    U->>A: Submit credentials
    A-->>B: 302 to redirect_uri with code
    B->>API: POST /token with code
    API->>A: Exchange code (server to server)
    A-->>API: access_token + refresh_token
    API-->>B: Set session cookie
    B-->>U: Signed in

Open this in the editor

Worked examples

1. Two participants, one round trip

`->>` is a solid arrow with a filled head, conventionally a request. `-->>` is dashed, conventionally the response. That convention is not enforced, but breaking it makes diagrams hard to skim.

sequenceDiagram
    Client->>Server: GET /orders
    Server-->>Client: 200 with order list

Open in the editor

2. Aliases and activation bars

`participant X as Long name` keeps the arrows short while the box stays readable. `activate`/`deactivate` draws the bar showing how long a participant is busy — useful for making a slow downstream call visible.

sequenceDiagram
    participant API as Order API
    participant DB as Postgres

    API->>DB: SELECT * FROM orders
    activate DB
    DB-->>API: 4,200 rows
    deactivate DB
    API->>API: Serialise response

Open in the editor

3. Branching with alt and opt

`alt`/`else` is a choice, `opt` is a step that may not happen. Every one of these blocks must be closed with `end` — an unclosed block is the most common sequence diagram error, and Mermaid reports it at the bottom of the file rather than at the block.

sequenceDiagram
    participant C as Checkout
    participant P as Payment provider

    C->>P: Authorise 49.90 EUR
    alt authorised
        P-->>C: approval code
        C->>C: Mark order paid
    else declined
        P-->>C: decline reason
        C->>C: Release stock reservation
    end
    opt fraud score high
        C->>C: Queue for manual review
    end

Open in the editor

4. Retry loops and notes

`loop` wraps repeated messages, and a `Note over` is the right place to record the thing a reader will otherwise ask — a timeout value, a limit, why the retry is bounded.

sequenceDiagram
    participant W as Worker
    participant S as Search index

    Note over W,S: Retries are capped at 5, then dead-lettered
    loop up to 5 attempts
        W->>S: PUT /documents/42
        S-->>W: 503 Service Unavailable
        W->>W: Exponential back-off
    end
    W->>W: Move to dead letter queue

Open in the editor

5. Parallel work and self-calls

`par` shows work happening simultaneously — the one thing prose is worst at describing. An arrow from a participant to itself is a legitimate way to show internal work without inventing a fake component.

sequenceDiagram
    participant O as Order service
    participant M as Mail service
    participant I as Invoice service
    participant A as Analytics

    O->>O: Commit transaction
    par notify customer
        O->>M: Send confirmation email
    and generate paperwork
        O->>I: Create invoice PDF
    and record metrics
        O->>A: Emit order_created
    end
    O-->>O: Return 201 to caller

Open in the editor

Sequence diagram syntax reference

Sequence diagrams have their own arrow vocabulary. None of it works in a flowchart, and flowchart arrows mostly do not mean what you expect here.

Syntax	Meaning
sequenceDiagram	Opens the diagram. Case-sensitive — `sequencediagram` fails.
participant A	Declares a participant, fixing left-to-right order.
participant A as Name	Alias — short id in the arrows, full name in the box.
actor A	Like participant, but drawn as a stick figure.
A->>B: text	Solid arrow, filled head. Conventionally a request.
A-->>B: text	Dashed arrow, filled head. Conventionally a response.
A->B: text	Solid line, no arrowhead.
A-)B: text	Open arrowhead — conventionally an async message.
A-xB: text	Arrow ending in a cross — conventionally a lost or failed message.
activate A / deactivate A	Draw an activation bar showing A is busy.
alt cond / else cond / end	Mutually exclusive branches.
opt cond / end	A block that may not run.
loop label / end	Repeated messages.
par label / and label / end	Concurrent branches.
Note over A,B: text	Note spanning participants. Also `Note left of` / `Note right of`.
autonumber	Number every message automatically.

Six errors that actually break sequence diagrams

Reproduced against Mermaid 11.12.2. Paste the broken version into the editor to see the exact error; the fixed version renders.

What you see

Parse error reported on the last line of the diagram

Why

A block opened and never closed. `alt`, `opt`, `loop` and `par` all need a matching `end`. Mermaid only notices when it runs out of input, so it blames the final line rather than the block you forgot.

Fix

Count openers against `end`s. When the error line is the last line of the file, this is almost always why.

Broken

sequenceDiagram
    A->>B: Request
    alt success
        B-->>A: OK

Fixed

sequenceDiagram
    A->>B: Request
    alt success
        B-->>A: OK
    end

What you see

Parse error on a message line

Why

A message with no colon. Every arrow needs `: text` after it, even when the text feels obvious.

Fix

Add the colon and a label.

Broken

sequenceDiagram
    Alice->>Bob hello

Fixed

sequenceDiagram
    Alice->>Bob: hello

What you see

No diagram type detected matching given configuration

Why

Wrong capitalisation of the keyword. Mermaid's diagram keywords are case-sensitive, and `sequencediagram` is not the same token as `sequenceDiagram`.

Fix

Capitalise the D.

Broken

sequencediagram
    A->>B: hi

Fixed

sequenceDiagram
    A->>B: hi

What you see

Trying to inactivate an inactive participant (B)

Why

A `deactivate` with no matching `activate`. Unlike the parse errors above this is a semantic check, so the message is a readable sentence rather than a token dump — but it still stops the diagram rendering.

Fix

Pair every `deactivate` with an `activate`, or drop both and let the arrows speak for themselves.

Broken

sequenceDiagram
    A->>B: Request
    deactivate B

Fixed

sequenceDiagram
    A->>B: Request
    activate B
    B-->>A: Response
    deactivate B

What you see

Parse error after a participant name

Why

A colon inside a message that Mermaid reads as the label separator is fine, but a stray `:` in a participant declaration is not — the declaration takes a name or an `as` alias, nothing else.

Fix

Use `as` for the display name.

Broken

sequenceDiagram
    participant API: Order service
    API->>DB: query

Fixed

sequenceDiagram
    participant API as Order service
    API->>DB: query

What you see

`end` appears as a participant instead of closing the block

Why

`end` is a keyword here too. Indentation does not decide what closes a block — the token does — so a node or participant called `end` collides with the block terminator.

Fix

Never name a participant `end`. Capitalise or rename it.

Broken

sequenceDiagram
    A->>end: finish

Fixed

sequenceDiagram
    A->>Endpoint: finish

Rendering notes

Measured against Mermaid 11.12.2 as this site runs it. Sequence diagrams behave differently from every other type here in two ways worth knowing.

Width is set by participant count, not message count

Three messages between two participants render to a viewBox of about 450×309. Forty messages between the same two participants render to 450×2011 — the width never moved. Adding participants widens the diagram; adding messages only lengthens it. Practically: a sequence diagram with more than about six participants becomes unreadably wide on a laptop long before the message count is a problem.

Sequence diagrams have a negative viewBox origin

Every other diagram type on this site starts its viewBox at `0 0`. Sequence diagrams start at `-50 -10` — mermaid reserves space to the left and above for participant boxes. This matters if you post-process the exported SVG: naive cropping code that assumes a zero origin will clip the leftmost participant.

PNG export works natively here

Sequence diagrams draw their labels as ordinary SVG text rather than embedded HTML, unlike flowchart, class, state and ER diagrams. That means the browser can rasterise them directly, so PNG export of a sequence diagram is pixel-identical to what you see on screen — no re-render, no typography shift.

Roughly 45px of height per message

Useful for guessing whether a diagram will fit a slide before you write it. Twenty messages is about 900 pixels tall, which is roughly the practical limit for a screenshot that stays legible without scrolling.

Theme changes colour, never layout

Rendering the same diagram with the default and dark themes gives a byte-identical viewBox, so participant boxes cannot shift or clip when the theme changes.

When to use something else

If most of your messages come from one participant to itself, you are describing an algorithm rather than a conversation, and a flowchart will read better.

If you find yourself adding `alt` blocks inside `alt` blocks, the branching has outgrown the format. Sequence diagrams show one path through a system beautifully and every path through a system very badly. Draw the happy path here and put the error handling in a separate diagram.

If what you actually need to communicate is which components exist and how they connect — rather than the order they talk in — no sequence diagram will help. That is an architecture diagram, and Mermaid's flowchart with subgraphs is a better fit for it.

Other diagram types

Written by Dominik Malsch · Last updated: September 8, 2026

Open the editor →