If you've ever needed to diagram how systems communicate how a browser talks to a server, how microservices exchange messages, or how a user flows through an authentication process sequence diagrams make that easy to explain visually. Mermaid.js takes it a step further: you write plain text, and it renders the diagram for you. No drag-and-drop tools. No exported image files to manage. Just code that lives right alongside your documentation.

That's why a mermaid.js sequence diagram code cheat sheet is so useful. When you know the syntax but can't remember whether it's ->> or -->> , or how to add a loop or an alt block, a quick reference saves you from context-switching out of your work. This guide covers the core syntax, practical examples, common pitfalls, and the patterns you'll actually use day to day.

What is a Mermaid.js Sequence Diagram?

A Mermaid.js sequence diagram is a text-based diagram that shows interactions between participants over time. You define participants, send messages between them, and Mermaid renders the visual. It follows UML sequence diagram conventions arrows represent messages, vertical lines show lifelines, and the order flows top to bottom.

You write the code inside a sequenceDiagram block, and Mermaid handles the rendering. It works in GitHub markdown, GitLab, Notion, VS Code with the Mermaid extension, and many documentation platforms.

If you've used PlantUML before, the mental model is similar, though the syntax differs. You can compare approaches with this PlantUML sequence diagram syntax reference if you're switching between tools.

How Do You Define Participants?

Participants are the actors or systems in your diagram. You can declare them explicitly or let Mermaid create them from your message definitions.

• Implicit declaration: Just use the name in a message. Mermaid creates the participant automatically.
• Explicit declaration: Use the participant keyword to control display order and give aliases.

sequenceDiagram
 participant B as Browser
 participant S as Server
 participant D as Database
 B->>S: GET /users
 S->>D: SELECT FROM users
 D-->>S: User data
 S-->>B: 200 OK

Using explicit declarations lets you control the left-to-right order of participants, which matters when your diagram has many actors.

What Arrow Types Are Available?

Arrow style communicates whether a message is synchronous, asynchronous, or a response. Here's the quick reference:

• ->> Solid line, open arrowhead (synchronous message)
• -->> Dashed line, open arrowhead (response)
• -> Solid line, closed arrowhead (asynchronous message)
• --> Dashed line, closed arrowhead (asynchronous response)
• -x Solid line, closed arrowhead with cross (message lost)
• --x Dashed line, open arrowhead with cross (response lost)

sequenceDiagram
 A->>B: Synchronous call
 B-->>A: Response
 A->B: Async message
 B--x A: Lost response

These map closely to standard UML notation. If you want a deeper look at how UML combined fragments work in sequence diagrams, the combined fragment examples guide covers that in detail.

How Do You Add Notes to Participants?

Notes add context without cluttering the message flow. You can attach a note to one participant or place it between two.

sequenceDiagram
 participant Client
 participant API
 Client->>API: POST /login
 Note right of API: Validate credentials
 Note over Client,API: TLS encrypted channel
 API-->>Client: 200 OK + token

Use Note left of, Note right of, or Note over with one or two participant names. Keep notes short they're annotations, not documentation.

How Do Loops, Alts, and Opts Work?

This is where sequence diagrams get practical for real-world flows. Mermaid supports several block types:

• Loop: Repeated interactions
• Alt: Conditional branches (if/else)
• Opt: Optional behavior (if without else)
• Par: Parallel execution
• Break: Breaking out of a flow
• Critical: Critical section

sequenceDiagram
 participant User
 participant App
 participant Auth

 User->>App: Submit login
 alt Valid credentials
 App->>Auth: Verify token
 Auth-->>App: Token valid
 App-->>User: Dashboard
 else Invalid credentials
 App-->>User: Error: 401
 end

 loop Every 60 seconds
 App->>Auth: Refresh token
 Auth-->>App: New token
 end

Each block ends with end. You can nest these a loop inside an alt, for example. For a more thorough breakdown of these constructs, see the loop, alt, and opt notation explanation.

How Do You Show Activations?

Activation bars show when a participant is actively processing. They're the thin rectangles that appear on a lifeline in traditional UML diagrams.

sequenceDiagram
 Client->>+Server: Request
 Server->>+Database: Query
 Database-->>-Server: Results
 Server-->>-Client: Response

Use + after the arrow type to activate, and - to deactivate. So ->>+ means "send a synchronous message and activate the receiver." The deactivation -->>- closes the bar.

How Do You Add Grouping and Backgrounds?

Use rect to add colored background regions. This is useful for highlighting phases or stages in a complex flow.

sequenceDiagram
 participant U as User
 participant S as Server

 rect rgb(200, 220, 255)
 Note over U,S: Authentication Phase
 U->>S: Login request
 S-->>U: Auth token
 end

 rect rgb(200, 255, 200)
 Note over U,S: Data Phase
 U->>S: GET /data
 S-->>U: JSON payload
 end

Can You Auto-Number Messages?

Yes. Add autonumber at the top of your diagram block to number every message sequentially. This is helpful when referencing specific steps in documentation or code reviews.

sequenceDiagram
 autonumber
 A->>B: First step
 B->>C: Second step
 C-->>B: Third step
 B-->>A: Fourth step

How Do You Style Sequence Diagrams?

Mermaid supports theming through %%{init: {'theme': 'dark'}}%% directives placed before the diagram block. You can also apply themes globally in your Mermaid configuration.

Available built-in themes include default, forest, dark, and neutral. For custom styling, the %%{init}%% block accepts JSON configuration for fonts, colors, and more. The Mermaid theming documentation covers all available options.

What Common Mistakes Break Mermaid Sequence Diagrams?

Most rendering failures come from a few recurring syntax errors:

• Missing end keyword: Every loop, alt, opt, par, and rect block must close with end. Forgetting this is the most common error.
• Using special characters in messages: Parentheses, colons, and semicolons in message text can break parsing. Wrap problematic text in quotes: A->>B: "Response (OK)"
• Mismatched participant names: If you declare participant A as Auth Service, you must use A (the alias) in your messages, not the full name.
• Incorrect arrow syntax: There's no space between the dashes and arrowheads. -->> works; -- >> doesn't.
• Missing activation pairs: If you use + to activate, make sure you close it with - at some point. Unmatched activations cause rendering issues.

What Does a Real-World Example Look Like?

Here's a typical OAuth login flow that combines most of the syntax covered above:

sequenceDiagram
 autonumber
 participant U as User
 participant C as Client App
 participant A as Auth Server
 participant R as Resource Server

 U->>C: Click "Login"
 C->>A: Authorization request
 Note over C,A: Includes client_id, redirect_uri, scope
 A-->>U: Login page
 U->>A: Submit credentials
 A->>A: Validate credentials
 alt Valid
 A-->>C: Authorization code (302 redirect)
 C->>A: Exchange code for token
 A-->>C: Access token + refresh token
 C->>R: GET /api/user (Bearer token)
 R-->>C: User profile JSON
 C-->>U: Render dashboard
 else Invalid
 A-->>C: Error: access_denied
 C-->>U: Show error message
 end

 loop Token refresh
 C->>A: Refresh token request
 A-->>C: New access token
 end

This shows participants, message types, notes, an alt block, a loop, and activation all in one diagram. It renders cleanly and communicates the full flow.

Where Does Mermaid.js Rendering Work?

You can render Mermaid sequence diagrams in several places without installing anything extra:

• GitHub: Markdown files and READMEs with fenced code blocks marked as mermaid
• GitLab: Same approach fenced mermaid blocks in markdown
• VS Code: Mermaid Preview extension renders diagrams inline
• Notion: Supports mermaid blocks natively
• Mermaid Live Editor: The official Mermaid live editor lets you write, preview, and export diagrams in the browser

Quick Reference Cheat Sheet

Here's the syntax you'll use most often, collected in one place:

Element	Syntax	Example
Start diagram	sequenceDiagram	First line of block
Participant	participant X as Label	participant S as Server
Sync message	->>	A->>B: Request
Response	-->>	B-->>A: OK
Async message	->	A->B: Notify
Note	Note right of X	Note right of S: Auth check
Loop	loop Description	loop Every 30s
Alt (if/else)	alt Condition	alt Success
Opt (if only)	opt Condition	opt Has admin role
Activation	+ and -	->>+S: Call
Auto-number	autonumber	Place at diagram top
Background color	rect rgb(r,g,b)	rect rgb(200,220,255)
End block	end	Required for all blocks

Checklist Before You Ship Your Diagram

• Every loop, alt, opt, par, break, critical, and rect block has a matching end
• Participant aliases match the names used in messages
• Activation + and - are paired correctly
• Message text avoids unescaped special characters
• Arrow types reflect the actual interaction model (sync vs. async, request vs. response)
• The diagram renders correctly in the Mermaid live editor before committing it to documentation
• Notes are brief and add context without repeating what the arrows already show
• Diagram reads top-to-bottom in chronological order without confusion