Mermaid.js Sequence Diagram Code Snippets and Examples

If you've ever needed to show how different parts of a system talk to each other over time, sequence diagrams are one of the clearest ways to do it. Mermaid.js makes this even easier by letting you write those diagrams in plain text, right inside your markdown files, documentation pages, or code comments. Instead of dragging boxes around in a drawing tool, you describe the interactions with a few lines of code and get a clean visual diagram automatically. That's why mermaid.js sequence diagram code snippets have become a go-to for developers, technical writers, and architects who want fast, version-controlled diagrams without leaving their workflow.

What does a mermaid.js sequence diagram actually look like?

At its core, a mermaid.js sequence diagram uses a simple syntax inside a sequenceDiagram block. You define participants (the actors or systems involved), then describe messages between them using arrows. Here's a basic example:

sequenceDiagram
 participant Browser
 participant Server
 participant Database

 Browser->>Server: GET /api/users
 Server->>Database: SELECT FROM users
 Database-->>Server: Return user rows
 Server-->>Browser: JSON response

This code produces a diagram showing a browser requesting data from a server, which queries a database and sends the result back. The ->> arrow means a solid line with an open arrowhead (a request), and -->> means a dashed line (a response). It reads almost like a conversation between the participants.

How do you add notes, loops, and conditions to a sequence diagram?

Real interactions are rarely linear. You often need to show conditional logic, repeated actions, or side notes. Mermaid.js supports all of these with straightforward syntax.

Adding notes

Place a note over one participant or between two using the Note keyword:

sequenceDiagram
 participant Client
 participant API

 Client->>API: POST /login
 Note right of API: Validate credentials
 API-->>Client: 200 OK

Using loops and conditions

Wrap message sequences in loop, alt, or opt blocks:

sequenceDiagram
 participant Browser
 participant Server

 loop Every 30 seconds
 Browser->>Server: Poll for updates
 Server-->>Browser: 200 OK (no changes)
 end

 alt Token valid
 Server-->>Browser: Return data
 else Token expired
 Server-->>Browser: 401 Unauthorized
 end

The alt block creates a split showing two possible paths, and you can add an else branch for each alternative. The opt block works the same way but for optional steps with no alternative.

Activations and deactivations

You can show when a participant is actively processing with + and - markers:

sequenceDiagram
 User->>+Auth Service: Login request
 Auth Service->>+Database: Query user
 Database-->>-Auth Service: User data
 Auth Service-->>-User: JWT token

The +Auth Service activation bar appears when the request arrives, and the -Auth Service closes it when the response is sent. This gives readers a visual sense of processing time per participant.

What are the most common mermaid.js sequence diagram code snippets developers copy?

Here are several real-world patterns that come up repeatedly in documentation and technical specs:

Simple request-response

sequenceDiagram
 Client->>API: GET /health
 API-->>Client: 200 OK

Authentication flow

sequenceDiagram
 participant User
 participant App
 participant AuthServer

 User->>App: Enter credentials
 App->>AuthServer: POST /oauth/token
 AuthServer-->>App: Access token
 App-->>User: Login success

Webhook notification

sequenceDiagram
 participant PaymentGateway
 participant WebhookEndpoint
 participant OrderService

 PaymentGateway->>WebhookEndpoint: POST /webhooks/payment
 WebhookEndpoint->>OrderService: Update order status
 OrderService-->>WebhookEndpoint: Acknowledged
 WebhookEndpoint-->>PaymentGateway: 200 OK

Error handling with try-catch

sequenceDiagram
 participant Client
 participant Service
 participant ExternalAPI

 Client->>Service: Submit form
 Service->>ExternalAPI: POST /process
 ExternalAPI-->>Service: 500 Error
 Note right of Service: Log error and retry
 Service->>ExternalAPI: POST /process (retry)
 ExternalAPI-->>Service: 200 OK
 Service-->>Client: Submission confirmed

These snippets are ready to paste into any tool that supports mermaid rendering GitHub markdown files, GitLab wikis, Notion pages, or static site generators like Docusaurus and MkDocs.

How does mermaid.js compare to other sequence diagram tools?

Mermaid.js isn't the only text-based diagramming option. PlantUML is another popular choice, and both tools let you write diagrams as code. The main differences come down to syntax style, rendering ecosystem, and feature depth. If you're weighing options, our comparison of sequence diagram scripting languages breaks down how mermaid, PlantUML, and other tools stack up.

For developers already familiar with PlantUML, we also maintain a set of PlantUML sequence diagram code examples so you can see how the same diagrams translate between formats.

What are the most common mistakes people make with mermaid sequence diagrams?

Misspelling participant names. If you declare a participant as Server but later write server in a message, mermaid will create a second participant called server. Participant names are case-sensitive and must match exactly.

Forgetting the end keyword. Every loop, alt, opt, and par block needs a closing end. Without it, the renderer will throw a syntax error.

Using the wrong arrow syntax. Solid arrows (->>) and dashed arrows (-->> ) mean different things request vs. response. Mixing them up makes the diagram misleading. Similarly, ->> (open arrowhead) is for asynchronous messages while ->> shows synchronous calls in some interpretations, so stay consistent with your team's conventions.

Overloading a single diagram. If your sequence diagram has 12 participants and 50 messages, it becomes harder to read than the code it's trying to explain. Break complex flows into smaller, linked diagrams.

Not rendering before committing. Always preview your mermaid diagram before merging it into documentation. A small typo can break the entire visual. The Mermaid Live Editor is a fast way to test snippets without setting up a local environment.

How do you handle lifeline activation, parallel messages, and self-calls?

Mermaid.js supports several advanced patterns beyond basic request-response flows:

Self-calls

sequenceDiagram
 participant Service
 Service->>Service: Internal validation

This shows a participant calling a method on itself, useful for depicting internal processing steps.

Parallel interactions

sequenceDiagram
 participant Client
 participant ServiceA
 participant ServiceB

 par Fan-out request
 Client->>ServiceA: Fetch profile
 Client->>ServiceB: Fetch preferences
 end
 ServiceA-->>Client: Profile data
 ServiceB-->>Client: Preferences data

The par block renders two message arrows at the same time, showing concurrent communication.

Reference to other diagrams

sequenceDiagram
 participant User
 participant System

 User->>System: Start process
 ref over System: See authentication flow
 System-->>User: Process complete

Use ref over to point readers to a related sequence diagram without duplicating the logic.

Where can you use mermaid.js sequence diagram code snippets?

Mermaid diagrams render natively in several platforms you might already be using:

GitHub Wrap your code in a mermaid fenced code block in any markdown file, issue, or pull request comment, and GitHub renders it automatically.
GitLab Same approach; mermaid blocks in markdown render inline.
Notion Add a code block, select "Mermaid," and paste your snippet.
VS Code Install the "Mermaid Markdown Syntax Highlighting" extension or use Markdown Preview to see diagrams in your editor.
Static site generators Docusaurus, MkDocs (with plugins), Hugo, and Jekyll all support mermaid rendering.
Confluence With the mermaid plugin, you can embed sequence diagrams directly in wiki pages.

If you need a broader overview of how sequence diagram syntax works across different tools, our UML sequence diagram syntax reference covers the foundational rules that apply to mermaid and other languages alike.

How do you style and configure mermaid.js sequence diagrams?

Mermaid lets you customize the look of your diagrams using %%{init}%% directives. Here's how to change the theme and font size:

%%{init: {'theme': 'dark', 'themeVariables': {'fontSize': '14px'}}}%%
sequenceDiagram
 participant A as Service A
 participant B as Service B
 A->>B: Request
 B-->>A: Response

You can also use autonumber at the top of your sequence diagram to automatically number each message, which is useful for referencing specific steps in technical discussions:

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

Quick checklist before you commit a mermaid sequence diagram

Participant names match exactly everywhere in the diagram (case-sensitive)
Every loop, alt, opt, and par block has a closing end
Arrow types are consistent solid for requests, dashed for responses
Diagram is previewed in the Mermaid Live Editor or your target platform before merging
Complex flows are split into smaller, focused diagrams instead of one overloaded visual
Notes and annotations add context without cluttering the message flow
autonumber is added if your team references specific steps in reviews or discussions

Start by picking one real interaction from your system a login flow, a payment webhook, an API call chain and write it out as a mermaid sequence diagram. Keep it to under 10 messages, render it in your docs platform, and share it with your team. That single diagram will likely save you more time in code reviews and onboarding than any paragraph of prose could.