Mermaid Sequence Diagram Cheat Sheet — Syntax Reference

A sequence diagram shows who talks to whom, and in what order. In Mermaid you write it as plain text: a sequenceDiagram header line, then one statement per line for participants, messages, notes and blocks. This page lists every statement you need, each with a copyable example, a short explanation and the mistake people make most often with it. The examples are the same snippets the editor inserts from its Syntax button, so what you read here is what the editor accepts.

Open in editor →

Participants and aliases

Mermaid creates participants in the order they first appear, so declaring them up front with participant fixes the left-to-right order. Use the as keyword to give a short id a longer display name; the id is what you type in messages, the alias is what the diagram shows. Writing actor instead of participant draws a stick figure.

participant — Declare a participant to control ordering.

participant Alice

alias — Short id with a display name.

participant A as Alice

Common mistake: A participant id cannot contain spaces. Writing participant Web App breaks later message lines, so declare participant W as Web App and send messages from W.

Arrows and messages

A message is sender, arrow, receiver, a colon, then the label. The arrow token decides the line style (solid or dashed) and the head (none, filled arrow, cross, or open arrow), so pick it to match the meaning: requests solid, replies dashed.

Token Result
-> Solid line without an arrowhead
--> Dashed line without an arrowhead
->> Solid line with an arrowhead
-->> Dashed line with an arrowhead
-x Solid line ending in a cross (lost or failed message)
--x Dashed line ending in a cross
-) Solid line with an open arrow (asynchronous message)
--) Dashed line with an open arrow (asynchronous message)

Solid arrow ->> — Synchronous message.

Alice->>Bob: Hello

Dashed arrow -->> — Dashed reply message.

Bob-->>Alice: Reply

Lost message -x — Message ending in a cross.

Alice-xBob: Lost message

Common mistake: Using -> and expecting an arrowhead. A plain -> draws a line with no head; use ->> for the usual arrow. Likewise, ->x is read as -> to a participant named x, so write the cross as -x.

Activations

Placing + right after the arrow activates the receiver and placing - after the arrow deactivates the sender, which draws the thin bar on the lifeline showing who is busy. The longhand activate Bob and deactivate Bob statements do the same thing.

Activation + / - — Activate and deactivate a lifeline.

Alice->>+Bob: Request
Bob-->>-Alice: Response

Common mistake: Deactivating a participant that was never activated. Mermaid reports an error for an unmatched deactivation, so every - needs an earlier + or activate for the same participant.

Notes

Notes attach commentary to one participant (left of or right of) or span several of them (over, with participants separated by commas). They are drawn in the flow at the point where they appear in the source.

Note over — Note spanning participants.

Note over Alice,Bob: Shared note

Note left of — Note beside a participant.

Note left of Alice: Note text

Note right of — Note beside a participant.

Note right of Bob: Note text

Common mistake: Leaving out the colon before the note text. The statement needs Note, a placement, the participant, a colon and then the text.

Fragments: loop, alt, opt, par, critical, break

Fragments wrap messages in a labelled frame. loop repeats, alt splits into alternatives with else, opt is optional, par runs branches in parallel with and, critical marks a region that must succeed with option for fallbacks, and break stops the flow. Every block is closed with end, and blocks can be nested.

loop — Repeat a block.

loop Every minute
    Alice->>Bob: Ping
end

alt / else — Alternative branches.

alt Success
    Alice->>Bob: OK
else Failure
    Alice->>Bob: Error
end

opt — Optional block.

opt Optional step
    Alice->>Bob: Maybe
end

par / and — Parallel branches.

par First
    Alice->>Bob: A
and Second
    Alice->>Bob: B
end

critical — Critical region with options.

critical Must succeed
    Alice->>Bob: Do it
option Fails
    Alice->>Bob: Fallback
end

break — Break out of the flow.

break Stop here
    Alice->>Bob: Abort
end

Common mistake: Using the wrong branch keyword or forgetting end. opt and loop have no else, par branches start with and, and critical branches start with option. A missing end makes the rest of the diagram a parse error.

Styling with rect and box

rect paints a coloured background behind the messages inside it, using an rgb() or rgba() colour, which is handy for highlighting a phase. box groups participant declarations under a labelled frame, which works as a swimlane for a team or a system.

rect — Colored background region.

rect rgb(200, 220, 255)
    Alice->>Bob: Highlighted
end

box — Group participants in a box.

box Team
    participant Alice
    participant Bob
end

Common mistake: Putting messages inside a box. A box only contains participant declarations; messages belong outside it, or inside a rect if you want a coloured band behind them.

Autonumber

The autonumber statement numbers every message that follows it, starting at 1, which makes long flows easy to reference in reviews and tickets.

autonumber — Number messages automatically.

autonumber

Common mistake: Adding autonumber after the messages you wanted numbered. Only messages below the statement get numbers, so put it directly under sequenceDiagram.

Comments and escapes

A line starting with %% is a comment and is ignored by the renderer. A semicolon ends a statement in Mermaid, so to show a literal semicolon in message text use the entity code #59;, which Mermaid renders as the character.

%% comment — Ignored by the renderer.

%% This is a comment

#59; escape — Literal semicolon in text.

Alice->>Bob: a#59; b

Common mistake: Typing a raw semicolon in a label or adding a comment at the end of a statement line. The semicolon splits the line into two statements, and comments must sit on their own line starting with %%.

Front matter title

A front matter block between two --- lines at the very top of the source sets the diagram title. It is configuration for the whole diagram, not a statement in the sequence, so it comes before the sequenceDiagram line.

---
title: My diagram
---

Common mistake: Placing the front matter below sequenceDiagram or leaving off the closing ---. Either way Mermaid no longer reads it as configuration.

Paste any of these into the Mermaid sequence diagram editor to see it rendered live, then export the result as SVG or PNG. Everything runs in your browser.