What are the arrow types in Mermaid sequence diagrams?

Mermaid sequence diagrams support several arrow types: ->> for solid arrow with arrowhead (synchronous call), -->> for dotted arrow with arrowhead (async response), -) for solid arrow with open end (async message), --) for dotted arrow with open end, -x for solid arrow with cross (lost message), and --x for dotted arrow with cross.

How do I show a loop in a Mermaid sequence diagram?

Use the 'loop' keyword followed by a description, then the messages inside the loop, and close with 'end'. For example: loop Every 5 seconds / Client->>Server: Ping / Server-->>Client: Pong / end. This draws a labeled rectangle around the repeated messages.

How do I add notes in Mermaid sequence diagrams?

Use 'Note right of Participant: text' or 'Note left of Participant: text' for notes beside a participant. Use 'Note over Participant1,Participant2: text' for a note spanning multiple participants. Notes appear as yellow sticky-note boxes in the rendered diagram.

What is the difference between activate and deactivate in Mermaid?

The 'activate' keyword draws a thicker lifeline bar on a participant, showing that it is actively processing. 'deactivate' ends the bar. You can also use the shorthand +/- notation: A->>+B activates B, and B-->>-A deactivates B. Activation bars visually show when a service is busy handling a request.

Mermaid Sequence Diagram Guide — Syntax & Examples

Basic Sequence Diagram

A sequence diagram shows how components communicate over time. Messages flow from left to right between named participants.

Mermaid ```mermaid sequenceDiagram Client->>Server: GET /api/users Server-->>Client: 200 OK (JSON) ```

->> is a solid arrow (request). -->> is a dotted arrow (response).

Arrow Types

->> — solid with arrowhead (synchronous call)
-->> — dotted with arrowhead (response)
-) — solid with open end (async fire-and-forget)
--) — dotted with open end
-x — solid with cross (lost/failed message)
--x — dotted with cross

Participants and Aliases

Declare participants explicitly to control their order and give them readable labels:

Mermaid ```mermaid sequenceDiagram participant U as User participant A as API Gateway participant S as Auth Service participant D as Database U->>A: Login request A->>S: Validate credentials S->>D: Query user D-->>S: User record S-->>A: JWT token A-->>U: 200 OK + token ```

Activation Bars

Show when a participant is actively processing with activate/deactivate or the shorthand +/-:

Mermaid ```mermaid sequenceDiagram Client->>+Server: POST /api/orders Server->>+DB: INSERT order DB-->>-Server: order_id Server-->>-Client: 201 Created ```

The + after ->> activates the target. The - deactivates it on the return arrow.

Loops

Wrap repeated messages in a loop block:

Mermaid ```mermaid sequenceDiagram participant C as Client participant S as Server loop Every 30 seconds C->>S: Health check S-->>C: 200 OK end ```

Conditional Logic (alt/opt)

Use alt for if/else and opt for optional blocks:

Mermaid ```mermaid sequenceDiagram User->>API: GET /profile API->>Auth: Verify token alt Token valid Auth-->>API: OK API->>DB: Fetch profile DB-->>API: Profile data API-->>User: 200 OK else Token expired Auth-->>API: Expired API-->>User: 401 Unauthorized end ```

Notes

Add explanatory notes to diagrams:

Mermaid ```mermaid sequenceDiagram participant C as Client participant S as Server Note over C,S: TLS handshake completed C->>S: Request with JWT Note right of S: Validate token signature S-->>C: Response ```

Note right of X: — note to the right
Note left of X: — note to the left
Note over X,Y: — note spanning participants

Real-World Example: OAuth 2.0 Flow

Mermaid ```mermaid sequenceDiagram participant U as User participant App as Client App participant Auth as Auth Server participant API as Resource API U->>App: Click "Login with Google" App->>Auth: Redirect to /authorize Auth->>U: Show consent screen U->>Auth: Grant permission Auth-->>App: Authorization code App->>Auth: Exchange code for token Auth-->>App: Access token + refresh token App->>API: Request with access token API-->>App: Protected resource ```

Tips

Always declare participants explicitly to control column order
Use aliases (participant A as API Gateway) for readable labels
Use activation bars to show request/response spans
Group related messages with rect for visual highlighting
Keep diagrams focused — one flow per diagram

For more diagram types, see What Is Mermaid? and Mermaid Flowcharts.

View Sequence Diagrams with MDViewer

MDViewer renders sequence diagrams as interactive SVGs with zoom and full-screen. Paste any example into a .md file and open it.

Download MDViewer

Requires macOS 13.0 or later. Intel and Apple Silicon.