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.
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 Alicealias — Short id with a display name.
participant A as AliceCommon 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: HelloDashed arrow -->> — Dashed reply message.
Bob-->>Alice: ReplyLost message -x — Message ending in a cross.
Alice-xBob: Lost messageCommon 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: ResponseCommon 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 noteNote left of — Note beside a participant.
Note left of Alice: Note textNote right of — Note beside a participant.
Note right of Bob: Note textCommon 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
endalt / else — Alternative branches.
alt Success
Alice->>Bob: OK
else Failure
Alice->>Bob: Error
endopt — Optional block.
opt Optional step
Alice->>Bob: Maybe
endpar / and — Parallel branches.
par First
Alice->>Bob: A
and Second
Alice->>Bob: B
endcritical — Critical region with options.
critical Must succeed
Alice->>Bob: Do it
option Fails
Alice->>Bob: Fallback
endbreak — Break out of the flow.
break Stop here
Alice->>Bob: Abort
endCommon 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
endbox — Group participants in a box.
box Team
participant Alice
participant Bob
endCommon 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.
autonumberCommon 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; bCommon 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.