Sequence Diagrams
Sequence diagrams show how components communicate over time. Each actor is laid out as a vertical lifeline; messages pass between lifelines horizontally.
Basic syntax
<div class="dp-mermaid language-mermaid">sequenceDiagram Alice->>Bob: Hello! Bob-->>Alice: Hi there Alice->>Bob: How are you? Bob-->>Alice: All good, thanks.</div>Participants
Declare participants explicitly to fix their order and give them readable labels:
<div class="dp-mermaid language-mermaid">sequenceDiagram participant B as Browser participant S as API Server participant D as Database B->>S: GET /users/42 S->>D: SELECT * FROM users WHERE id=42 D-->>S: user row S-->>B: 200 { id: 42, name: "Alice" }</div>Use actor instead of participant to render a stick-person icon:
Message arrow types
<div class="dp-mermaid language-mermaid">sequenceDiagram A->>B: Solid arrowhead (sync request) A-->>B: Dotted arrowhead (sync response) A->B: Solid, no arrowhead A-->B: Dotted, no arrowhead A-xB: Solid with cross (lost message) A--xB: Dotted with cross A-)B: Async (open arrowhead) A--)B: Async dotted</div>| Syntax | Meaning |
|---|---|
->> | Synchronous call (solid arrowhead) |
-->> | Synchronous response (dotted arrowhead) |
-> | Solid, no arrowhead |
--> | Dotted, no arrowhead |
-x | Lost / dropped message |
--x | Lost / dropped dotted |
-) | Asynchronous (open arrowhead) |
--) | Asynchronous dotted |
Activation boxes
Activation boxes indicate when a participant is actively processing. Use the +/- shorthand directly on the message:
Or use explicit activate / deactivate:
Nested +/- on the same participant creates stacked boxes to show re-entrant calls:
Notes
Annotate the diagram with free-form notes:
<div class="dp-mermaid language-mermaid">sequenceDiagram participant A participant B Note right of A: Waiting for user input Note left of B: Validates on every request A->>B: Submit Note over A,B: Both sides log this event</div>| Syntax | Position |
|---|---|
Note right of X | Right of X |
Note left of X | Left of X |
Note over X | Centred above X |
Note over X,Y | Spanning X to Y |
Loop
Repeat a block of messages:
<div class="dp-mermaid language-mermaid">sequenceDiagram Client->>Server: Subscribe to events loop Every 30 seconds Server->>Client: Heartbeat ping Client-->>Server: Pong end Client->>Server: Unsubscribe</div>Alt / else
Model branching flows — alt with one or more else clauses:
Opt
An optional block (shown only when the condition holds):
<div class="dp-mermaid language-mermaid">sequenceDiagram User->>App: Submit form App->>Validator: Validate fields opt Invalid input Validator-->>App: Validation errors App-->>User: Show error messages end App->>DB: Persist record DB-->>App: OK App-->>User: Success</div>Par
Show parallel concurrent activity:
<div class="dp-mermaid language-mermaid">sequenceDiagram Server->>Server: Receive request par Notify user Server->>Email: Send confirmation and Log event Server->>Logger: Write audit log and Update metrics Server->>Metrics: Increment counter end Server-->>Client: 200 OK</div>Critical
A critical block marks a section that must succeed, with option branches for alternative outcomes:
Break
Model an early exit from a sequence:
<div class="dp-mermaid language-mermaid">sequenceDiagram User->>App: Upload file break File too large App-->>User: 413 Payload Too Large end App->>Storage: Store file Storage-->>App: URL App-->>User: 200 { url }</div>Autonumber
Prefix every message with an incrementing sequence number:
<div class="dp-mermaid language-mermaid">sequenceDiagram autonumber Browser->>Server: GET /api/data Server->>DB: Query DB-->>Server: Rows Server-->>Browser: JSON response</div>Box grouping
Group participants in a colored background box:
<div class="dp-mermaid language-mermaid">sequenceDiagram box "Front-end" #e0f2fe participant UI participant Store end box "Back-end" participant API participant DB end UI->>API: Fetch API->>DB: Query DB-->>API: Rows API-->>Store: Update state Store-->>UI: Re-render</div>Rendering with @domphy/mermaid
Build-time:
import { renderMermaidToSvg } from "@domphy/mermaid"
const svg = await renderMermaidToSvg(`sequenceDiagram
autonumber
actor User
participant App
participant Auth
User->>App: Sign in
App->>+Auth: Verify credentials
Auth-->>-App: JWT token
App-->>User: Redirect to /dashboard`, { theme: "default" })Client-side (for dynamic or user-authored diagrams):
import { mermaidClient } from "@domphy/mermaid"
const SequenceView = {
pre: [{ code: `sequenceDiagram
A->>B: Hello
B-->>A: Hi` }],
$: [mermaidClient({ theme: "neutral" })],
}