Skip to main content

Mermaid 11.15.0

Mermaid sequence diagram cheat sheet

Sequence diagrams show messages exchanged between participants over time. Use a flowchart for branching work, or a class diagram for static types and relationships.

Build this in Sequence Diagram Generator →

Quick start

Declare aliases first to control lifeline order, then write each message as sender, arrow, receiver and text.

Mermaid
Open in editor → 
sequenceDiagram
  actor R as Reader
  participant S as Search service
  R->>+S: Find guide
  S-->>-R: Return results

Loading…

Syntax reference

Syntax reference
SyntaxMeaning
sequenceDiagram / participant / actor / asDeclare lifelines and human-readable aliases; actor uses a person symbol.
participant A@{ "type": "boundary" }Participant types: boundary, control, entity, database, collections, queue; use participant or actor for ordinary lifelines.
->Solid line, no arrowhead.
-->Dotted line, no arrowhead.
->>Solid arrow.
-->>Dotted arrow.
<<->>Solid bidirectional arrow.
<<-->>Dotted bidirectional arrow.
-xSolid line ending in a cross.
--xDotted line ending in a cross.
-)Solid open arrow for asynchronous messages.
--)Dotted open arrow for asynchronous messages.
-|\Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
--|\Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
-|/Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
--|/Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
/|-Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
/|--Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
\\-Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
\\--Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
-\\Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
--\\Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
-//Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
--//Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
//-Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
//--Half-arrow variant: orientation and solid/dotted strokes are shown in the example.
A->>()B / A()->>B / A()->>()BAttach a message to the center of the sending or receiving lifeline.
activate / deactivate / ->>+ / -->>-Start and end activation bars; balanced nested activations are allowed.
create participant / create actor / destroyCreate before the first incoming message; destroy before the message that ends the lifeline.
Note left of / right of / over A,BPosition a note beside or across lifelines. Use <br/> for line breaks.
loop / alt / else / opt / par / and / critical / option / break / rect / endControl blocks close with end. Rect takes a background color; alternatives belong to their enclosing block.
autonumber / autonumber 10 5Number messages automatically; optional start and increment values.
box Color Label / endGroup participant declarations into a colored or transparent box.
link A: Label @ URL / links A: {"Label":"URL"}Attach a single link or a JSON menu to a participant.
%% / accTitle: / accDescr:Comments and accessible diagram descriptions.

Participant symbols and aliases

Ids stay short; aliases carry the display text. JSON configuration changes participant symbols. Declare all lifelines before messages for predictable horizontal order.

Mermaid
Open in editor → 
sequenceDiagram
  actor R as Reader
  participant B@{ "type": "boundary" }
  participant C@{ "type": "control" }
  participant E@{ "type": "entity" }
  participant D@{ "type": "database" }
  participant L@{ "type": "collections" }
  participant Q@{ "type": "queue" }
  R->>B: Request
  B->>C: Validate
  C->>E: Read
  E->>D: Query
  D-->>L: Results
  L-)Q: Notify

Loading…

Line, arrowhead and half-arrow variants

Select the arrow for the convention used in your documentation. Open arrows often mean asynchronous delivery. A cross on an ordinary message is a visual marker; destroy explicitly ends the lifeline.

Mermaid
Open in editor → 
sequenceDiagram
  participant A as Sender
  participant B as Receiver
  A->B: Message
  A-->B: Message
  A->>B: Message
  A-->>B: Message
  A<<->>B: Message
  A<<-->>B: Message
  A-xB: Message
  A--xB: Message
  A-)B: Message
  A--)B: Message
  A-|\B: Message
  A--|\B: Message
  A-|/B: Message
  A--|/B: Message
  A/|-B: Message
  A/|--B: Message
  A\\-B: Message
  A\\--B: Message
  A-\\B: Message
  A--\\B: Message
  A-//B: Message
  A--//B: Message
  A//-B: Message
  A//--B: Message
  A()->>()B: Center connection

Loading…

Creation, destruction and activation

Place create immediately before the message that introduces the new participant. Destroy immediately precedes its terminating message. Balance every activation so later messages do not inherit an unintended bar.

Mermaid
Open in editor → 
sequenceDiagram
  participant C as Controller
  create participant W as Worker
  C->>+W: Start job
  Note right of W: Temporary process
  W-->>-C: Job complete
  destroy W
  C-xW: Stop process

Loading…

Loops, alternatives and parallel branches

Each block ends with end. Else belongs to alt; and separates par branches. Opt adds a single optional branch. Critical can include option recovery branches; break represents an exceptional exit.

Mermaid
Open in editor → 
sequenceDiagram
  participant C as Client
  participant S as Service
  loop Retry
    C->>S: Request
    alt Accepted
      S-->>C: Result
    else Rejected
      S-->>C: Error
    end
  end
  opt Cache hit
    S-->>C: Cached result
  end
  par Logging
    S->>S: Record
  and Metrics
    S->>S: Count
  end
  critical Commit
    S->>S: Save
  option Failure
    S-->>C: Roll back
  end
  break Timeout
    S-->>C: Stop
  end
  rect rgb(230,240,255)
    Note over C,S: Review boundary
  end

Loading…

Sequence layout options

Mirror actors at the bottom only when the diagram is long enough to benefit. Message wrapping and actor spacing affect readability; they do not change message order.

Mermaid
Open in editor → 
---
config:
  sequence:
    mirrorActors: false
    wrap: true
    actorMargin: 60
---
sequenceDiagram
  participant R as Reader
  participant G as Guide
  R->>G: Read reference

Loading…

Common mistakes

Leaving a block open

Add end for each nested block.

Invalid syntax — corrected example below

sequenceDiagram
  loop Retry
    A->>B: Request
Mermaid
Open in editor → 
sequenceDiagram
  loop Retry
    A->>B: Request
  end

Loading…

Using end as bare message text

The parser treats end specially. Quote or bracket that word when it causes ambiguity, and keep participant ids distinct from control keywords.

Limitations

  • Horizontal position follows declarations and layout rules; lifelines are not freely draggable.
  • Messages show source order, not a numerical time scale.
  • Participant menus and click behavior depend on the embedding host.

Frequently Asked Questions

What is the difference between actor and participant?
Actor draws a person symbol; participant normally draws a box. Both can send and receive messages, and participant supports additional symbol types.
How do I add a response arrow?
Use -->> for a dotted response arrow. Append a minus when the message should also end an activation.
How do I show simultaneous work?
Use par with and-separated branches and close the block with end.