Sequence diagram
sequenceDiagram
autonumber
actor Shopper
participant Web
participant Orders
Shopper->>+Web: Place order
Web->>Orders: Create order
loop Every minute
Orders-->>Orders: Check payment
end
Orders-->>Web: Done
Web-->>-Shopper: Confirmation email
timeline:
enter Shopper-Web slide-left
enter Web-Orders slide-left
enter loop:1 fade, enter Orders-Orders fade, highlight loop:1 glow
unhighlight loop:1, enter Orders-Web slide-right, enter Web-Shopper slide-right
Participants
A participant can be declared first, or used straight away in a message: as in Mermaid, a participant nothing declares is created the first time it is named.
| Syntax | Description |
|---|---|
participant Web |
A box |
actor Shopper |
A stick figure, always 36px wide; a longer name is drawn beneath it and may be wider |
participant A as Order Service |
A is the id, Order Service is the name drawn |
- Ids may contain only letters, digits and
_. To show a name with other characters or spaces, useas. - Participants are laid out left to right in the order they are first named, by a declaration or a message. A later
participant X as Namesets the name without moving the lane. - When the same id is declared twice, the first declaration is kept and a warning is reported.
Messages
The syntax is <from><arrow><to>: text. The colon is required; the text may be empty.
| Arrow | Line | Arrowhead |
|---|---|---|
->> |
Solid | Filled arrow |
-->> |
Dotted | Filled arrow |
-> |
Solid | None |
--> |
Dotted | None |
-x |
Solid | Cross |
--x |
Dotted | Cross |
-) |
Solid | Open arrow (async) |
--) |
Dotted | Open arrow (async) |
<<->> |
Solid | Bidirectional |
<<-->> |
Dotted | Bidirectional |
A participant can also message itself: Orders->>Orders: Retry.
Activation bars
- Shorthand:
A->>+B: Callactivates the receiver B;B-->>-A: Returnends the activation of the sender B. - Full syntax:
activate B,deactivate B. - Activations can stack several deep. Writing
deactivatewhen nothing is active reports an error and the line is skipped.
Note
sequenceDiagram
participant A
participant B
A->>B: ping
note right of B: Received
note over A,B: A round trip
note left of A: text, note right of A: text, note over A: text, note over A,B: text.
Blocks
sequenceDiagram
participant Client
participant API
alt Signed in
Client->>API: Fetch data
else Signed out
Client->>API: Sign in
end
par At the same time
API-->>Client: Data
and
API-->>Client: Notification
end
rect rgba(99, 102, 241, 0.1)
Client->>API: Background sync
end
| Block | Syntax |
|---|---|
| Loop | loop condition … end |
| Optional | opt condition … end |
| Break | break condition … end |
| Alternatives | alt condition … else condition … end |
| Parallel | par label … and label … end |
| Critical region | critical label … option label … end |
| Background color | rect rgb(...) or rect rgba(...) … end |
- Blocks can be nested to any depth; a missing
endreports an error. rectaccepts onlyrgb()andrgba();rect #hexorrect bluereports an error.
Other syntax
Keywords are read in any case, as in Mermaid: Note RIGHT OF A, Participant A AS Alice and Loop … End all work.
Only a whole line whose first characters are %% is a comment. A %% in the middle of a line is text, as in Mermaid: A->>B: 50%% done draws “50%% done”, and participant A %% x declares a participant named “A %% x”. After the header, after end, autonumber or a ;, a %% is still a comment; after an activate or deactivate naming an unknown participant, after a rect color, or glued to a one-letter name, it is an error. Put comments on a line of their own.
| Syntax | Description |
|---|---|
autonumber / autonumber off |
Numbers the messages / stops numbering. A start value and step (autonumber 10 5) are not supported |
box color title … end |
Groups participants in a box. If the first word is a color (#hex, rgb(), transparent or a CSS color name) it is used as the color, and the rest as the title. Only participant / actor declarations may go inside |
create participant X, create actor X |
The participant appears from its creating message: the message right after the create, which must be sent to X. X’s box is drawn on that message’s arrow and its lifeline starts there. The create must come before X is first named, a create whose next message is not sent to X is an error, and nothing may stand between the two (a note, activate, autonumber, a block boundary or another create/destroy is an error). A create with no message after it draws nothing and reports a warning. A created participant is also drawn in the bottom row, and when anything is drawn before its create, its lane sits half a lane further right |
destroy X |
The participant’s lifeline ends on its destroying message: the message right after the destroy, which X must send or receive. X’s box is drawn a second time on that message’s arrow and the lifeline stops under it; the rows after it move down. A destroy whose next message does not name X is an error, nothing may stand between the two, and a destroy with no message after it draws nothing and reports a warning. destroy never creates a participant nothing else names |
link A: label @ url |
Turns the participant’s box into a link. A participant nothing declares is created where the link is written |
links A: {"Label": "url", ...} |
Several links on one participant, as JSON |
title Title, title: Title, accTitle: Title |
The diagram title; accTitle is read by screen readers only |
accDescr: text, accDescr { ... } |
The screen-reader description, on one line or in a braced block |
Timeline targets
| Element | id | Example |
|---|---|---|
| Participant | The declared id (not the name after as) |
Web |
| Message | from-to, with #2 for a repeat, counted in source order across all blocks |
Web-Orders, Web-Orders#2 |
| Block | kind:N, numbered separately for each kind of block |
loop:1, alt:1, opt:1, par:1, critical:1, break:1, rect:1 |
| box | box:N |
box:1 |
| Note | note:N, in source order |
note:1 |
| Activation bar | activation:N, in the order the bars open |
activation:1 |
- A participant’s top and bottom boxes, its lifeline and the closing box of a
destroyanimate together. - Animating a
boxaffects only the background band; the participants inside must be targeted separately. - The sections split off by
else,andandoptioncannot be targeted on their own.
Not yet supported
| Syntax | Current behavior |
|---|---|
| Participant ids with spaces or quotes | Error; use participant A as Display Name |
participant A@{ "type": ... } |
Error |
autonumber 10 5 |
Error |
properties, details |
Error |