Every developer who works on a team knows the pain of explaining how a system communicates which service calls what, in what order, and what happens when something fails. Writing that out in plain text gets messy fast. Mermaid sequence diagrams solve this by letting you describe interactions using simple text-based syntax that renders into clean, visual diagrams. If you've ever Googled a specific syntax keyword and couldn't remember if it's Note right of or Note over, you already know why a cheat sheet like this exists.

What is a Mermaid sequence diagram?

A Mermaid sequence diagram is a text-based diagram that shows how different actors or components exchange messages over time. You write it in a Markdown-like syntax, and tools like GitHub, VS Code, or the Mermaid Live Editor render it into a visual chart. The diagram reads top to bottom, with each vertical line (called a lifeline) representing a participant, and arrows between them showing messages.

This matters for developers because sequence diagrams live right inside your codebase or documentation. No need to open a design tool, draw boxes, and manually sync them with your code changes. Update the text, and the diagram updates too.

How do you start a basic sequence diagram?

Every Mermaid sequence diagram starts with the sequenceDiagram keyword. From there, you define participants and the messages between them.

sequenceDiagram
 participant Client
 participant Server
 participant Database

 Client->>Server: Send login request
 Server->>Database: Query user credentials
 Database-->>Server: Return user data
 Server-->>Client: Return auth token

Here's what each piece does:

  • participant Declares an actor or component. You can rename them with an alias: participant U as User
  • ->> Solid arrow (synchronous message)
  • -->> Dashed arrow (asynchronous or response message)
  • Note right of / Note left of / Note over Adds annotations to a lifeline or range of lifelines

If you're just getting started with Mermaid syntax, our beginner's guide to writing Mermaid diagram syntax covers the fundamentals you'll need before diving into sequence-specific features.

What arrows and message types can you use?

This is where most developers need a quick reference. Mermaid supports several arrow styles, and each one communicates something different about the interaction:

sequenceDiagram
 participant A as Service A
 participant B as Service B

 A->>B: Solid arrow (request)
 A-->>B: Dashed arrow (async/callback)
 A->>B: Solid with text
 B-->>A: Dashed return
 A-xB: Solid with cross (async, lost message)
 A--xB: Dashed with cross
 A-)B: Solid open arrowhead (async, no return)
 A--)B: Dashed open arrowhead

Quick reference table:

  • ->> Solid line, filled arrowhead
  • -->> Dashed line, filled arrowhead
  • ->>B Solid line, open arrowhead (fire and forget)
  • ->xB Solid line, cross (message lost or error)

For a deeper reference on Mermaid scripting across all diagram types, check out the full Mermaid scripting guide.

How do you add notes, loops, and conditions?

Real interactions aren't just straight-line message chains. You need to show retry logic, conditional branches, and parallel operations. Mermaid handles all of this with keywords that wrap message blocks.

sequenceDiagram
 participant User
 participant App
 participant API

 User->>App: Click "Submit"

 Note over App: Validate form input

 alt Input is valid
 App->>API: POST /submit
 API-->>App: 200 OK
 App-->>User: Show success message
 else Input is invalid
 App-->>User: Show validation errors
 end

 opt User retries
 User->>App: Click "Submit" again
 App->>API: POST /submit
 end

 loop Every 30 seconds
 App->>API: GET /status
 API-->>App: Status response
 end

Key syntax for control flow

  • alt / else / end If/else conditional blocks
  • opt / end Optional block (runs once or not at all)
  • loop / end Repeated action with a label
  • par / and / end Parallel execution
  • critical / option / end Critical region with optional recovery
sequenceDiagram
 par Request A
 Client->>Service1: Get user data
 Service1-->>Client: User data
 and Request B
 Client->>Service2: Get preferences
 Service2-->>Client: Preferences
 end

How do you group and label sections?

When a sequence diagram gets long, grouping related messages helps readers follow the flow. Use rect to add a colored background behind a section of your diagram.

sequenceDiagram
 participant Browser
 participant Server
 participant Auth

 rect rgb(200, 220, 255)
 Note over Browser, Auth: Authentication Phase
 Browser->>Server: GET /dashboard
 Server->>Auth: Validate token
 Auth-->>Server: Token valid
 Server-->>Browser: Dashboard HTML
 end

 rect rgb(220, 255, 220)
 Note over Browser, Server: Data Loading Phase
 Browser->>Server: GET /api/data
 Server-->>Browser: JSON payload
 end

You can also use box in newer Mermaid versions to visually group participants themselves.

How do you handle activation and deactivation?

Activation bars show when a participant is actively processing a request. They're the thin rectangles you see on lifelines in formal UML diagrams.

sequenceDiagram
 Client->>+Server: Send request
 Server->>+Database: Query
 Database-->>-Server: Results
 Server-->>-Client: Response

The + after the arrow activates the receiving participant. The - deactivates it. This helps readers see which component is "busy" at any point in the sequence.

How do you set diagram themes and configuration?

Mermaid lets you configure the look of your diagrams using %%{init}%% directives placed before the diagram content.

%%{init: {'theme': 'dark', 'sequence': {'mirrorActors': false, 'messageAlign': 'center'}}}%%
sequenceDiagram
 participant A
 participant B
 A->>B: Message

Common configuration options for sequence diagrams:

  • mirrorActors Show participant names at the bottom too (default: true)
  • messageAlign Align message text: left, center, or right
  • actorMargin Horizontal spacing between participants
  • width / height Control box dimensions for participants

If you work with Gantt charts alongside your sequence diagrams, you might find our Mermaid Gantt chart scripting reference useful for keeping project timelines in the same documentation system.

What are the most common mistakes developers make?

After working with Mermaid in dozens of codebases, these mistakes come up over and over:

  1. Forgetting end keywords. Every alt, loop, opt, par, and rect block needs a matching end. A missing end will break the entire diagram with a cryptic parse error.
  2. Using the wrong arrow syntax. Writing -> instead of ->> is a common typo. The double angle bracket matters.
  3. Not declaring participants. You can use participants without declaring them, but explicit declarations let you control display names and ordering.
  4. Overloading a single diagram. If your sequence diagram has 15 participants and 80 messages, it's too complex. Break it into smaller, focused diagrams.
  5. Special characters in messages. Parentheses, semicolons, and certain punctuation can confuse the parser. Use quotes around message text when in doubt: A->>B: "Hello (world)"
  6. Ignoring lifeline order. Participants appear in the order you declare them. If the visual order looks wrong, reorder your participant lines.

What does a real-world API flow look like?

Here's a practical example showing an OAuth2 authentication flow the kind of diagram you'd actually put in your project wiki:

sequenceDiagram
 actor User
 participant Browser
 participant App as App Server
 participant Auth as Auth Provider
 participant API as Resource API

 User->>Browser: Click "Sign In"
 Browser->>App: GET /auth/login
 App->>Auth: Redirect to auth URL

 rect rgb(255, 240, 230)
 Note over User, Auth: External Auth Flow
 Auth-->>Browser: Login page
 User->>Browser: Enter credentials
 Browser->>Auth: POST credentials
 Auth->>Auth: Validate & generate code
 Auth-->>Browser: Redirect with auth code
 end

 Browser->>App: GET /auth/callback?code=abc123
 App->>Auth: Exchange code for token
 Auth-->>App: Access + refresh tokens
 App->>App: Store tokens securely
 App-->>Browser: Set session cookie

 User->>Browser: Access protected page
 Browser->>App: GET /dashboard (with cookie)
 App->>API: GET /data (Bearer token)
 API-->>App: Protected data
 App-->>Browser: Rendered page

This shows real patterns: external redirects, error boundaries with rect, and multi-party token exchanges. It's the kind of diagram that prevents confusion during code review.

How do you make sequence diagrams work in GitHub and docs?

Mermaid renders natively in GitHub Markdown files, GitLab, Notion, and many static site generators. Just wrap your diagram in a fenced code block:

```mermaid
sequenceDiagram
 A->>B: Hello
```

For documentation sites, tools like Docusaurus, MkDocs, and Hugo all support Mermaid through plugins. If you're building a developer portal, embedding these diagrams directly in your API docs means they stay current without manual image exports.

Quick reference: all sequence diagram keywords

Keep this list handy when writing your next diagram:

  • sequenceDiagram Opens the diagram
  • participant Declare a lifeline
  • actor Declare a human actor (renders differently)
  • ->> / -->> Solid / dashed arrows
  • -> / --> Arrows without arrowheads
  • Note over / Note left of / Note right of Annotations
  • alt / else / end Conditional blocks
  • opt / end Optional blocks
  • loop / end Loop blocks
  • par / and / end Parallel execution
  • critical / option / end Critical sections
  • break / end Break out of a loop or critical section
  • rect / end Colored background region
  • activate / deactivate Show activation bars
  • destroy Mark a participant as destroyed
  • %%{init}%% Set configuration and theme
  • autonumber Automatically number messages

Practical checklist before you ship your diagram

  1. Check that every block has a matching end count your opens and closes
  2. Verify arrow syntax double check ->> vs -> for each message
  3. Order your participants make sure the visual layout matches the logical flow
  4. Keep it under 10-12 participants split into separate diagrams if needed
  5. Test in the Mermaid Live Editor before committing to your repo
  6. Add a title using %%{init}%% or a preceding heading in your docs so readers know what they're looking at
  7. Use autonumber for complex flows it makes discussions during code review much easier ("look at step 7")
  8. Escape special characters in message text to avoid parse errors

Start by copying one of the examples above into your project's README or docs. Get it rendering, then modify the participants and messages to match your actual system. You'll have a working diagram in under five minutes, and your team will thank you the next time someone asks "how does the auth flow work?"