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, use as.
  • 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 Name sets 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: Call activates the receiver B; B-->>-A: Return ends the activation of the sender B.
  • Full syntax: activate B, deactivate B.
  • Activations can stack several deep. Writing deactivate when 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 end reports an error.
  • rect accepts only rgb() and rgba(); rect #hex or rect blue reports 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 destroy animate together.
  • Animating a box affects only the background band; the participants inside must be targeted separately.
  • The sections split off by else, and and option cannot 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