If you've ever needed to show how different parts of a system talk to each other a user clicking a button, a server fetching data, a database responding you know that plain text descriptions get messy fast. That's where Mermaid sequence diagrams come in. They let you turn simple text into clear, visual diagrams that show the flow of messages between components. And the best part is you don't need any design skills to create them. This guide walks you through the Mermaid sequence diagram syntax so you can start building your own diagrams today.

What is a Mermaid sequence diagram?

A Mermaid sequence diagram is a visual chart that shows how different participants (like users, servers, or services) exchange messages over time. You write it using Mermaid's text-based syntax, and a renderer turns that text into a diagram with arrows showing the order of interactions.

Mermaid itself is a JavaScript-based diagramming tool that uses a Markdown-like syntax. It's supported on GitHub, GitLab, Notion, and many documentation platforms. You can read more about the core Mermaid syntax and how Markdown diagramming works if you're brand new to the tool.

Why would someone use a sequence diagram instead of other diagram types?

Sequence diagrams are specifically designed to show time-ordered interactions. While flowcharts show decision paths and class diagrams show structure, sequence diagrams answer the question: "What happens first, second, third and who talks to whom?"

This makes them especially useful when you're documenting:

• API request and response flows
• Authentication or login processes
• Microservice communication patterns
• User interactions with a frontend and backend
• Any multi-step workflow between systems or people

How do you write a basic sequence diagram?

Every Mermaid sequence diagram starts with the keyword sequenceDiagram. After that, you define participants and then describe the messages between them.

Here's a minimal example:

sequenceDiagram
 participant User
 participant Server
 User->>Server: Send login request
 Server-->>User: Return auth token

The arrows represent messages. The >> arrow is a solid line (synchronous), and the -->> arrow is a dashed line (asynchronous or a response). The text after the colon is the message label.

Declaring participants

You can declare participants in two ways:

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

Example with aliases:

sequenceDiagram
 participant U as User
 participant S as Auth Server
 participant DB as Database
 U->>S: Login with credentials
 S->>DB: Query user record
 DB-->>S: User data
 S-->>U: Auth token

Using aliases keeps your diagram labels clean while your code stays readable.

What arrow types are available?

Mermaid offers several arrow styles to represent different kinds of interactions:

• ->> Solid arrow (synchronous message)
• -->> Dashed arrow (asynchronous or return message)
• -x Solid arrow with a cross (message lost or failed)
• --x Dashed arrow with a cross
• -) Solid arrow with an open end (async, older style)
• --) Dashed arrow with an open end

Choosing the right arrow helps readers quickly understand whether a message expects a response, is fire-and-forget, or failed.

How do you add notes to a sequence diagram?

Notes add context without cluttering the message flow. You can attach a note to a specific participant at a specific point in the sequence.

sequenceDiagram
 participant Client
 participant API
 Client->>API: GET /users
 Note right of API: Fetches user list from database
 API-->>Client: 200 OK with user data

You can also position notes left of or right of a participant. If a note applies to two participants, use over:

Note over Client,API: TLS handshake occurs here

Can you show loops, conditions, and alternative flows?

Yes, and this is where sequence diagrams get really powerful. Mermaid supports several control structures:

Loops

loop Every 30 seconds
 Client->>Server: Poll for updates
 Server-->>Client: Return changes
end

Conditions (alt/else)

alt User is authenticated
 Server-->>Client: Return protected data
else User is not authenticated
 Server-->>Client: 401 Unauthorized
end

Optional blocks (opt)

opt User has admin role
 Server->>DB: Delete user record
end

These blocks let you document real-world scenarios where flows branch or repeat, rather than just showing the happy path.

How do you add titles and organize longer diagrams?

For longer sequences, you can add a title to make the diagram self-explanatory:

sequenceDiagram
 title: User Registration Flow
 participant Browser
 participant API
 participant DB
 Browser->>API: POST /register
 API->>DB: Insert new user
 DB-->>API: Success
 API-->>Browser: 201 Created

You can also use autonumber at the top of your diagram to automatically number each message. This is helpful when you're discussing a specific step with your team and want to reference it by number.

sequenceDiagram
 autonumber
 participant A
 participant B
 A->>B: First message
 B-->>A: Reply

What are the most common mistakes beginners make?

• Forgetting the arrow syntax: Using a single > instead of >> will break your diagram. Always use double chevrons for message arrows.
• Not closing blocks: Every loop, alt, and opt block needs a matching end. Missing one will cause a parse error.
• Using special characters in labels: Parentheses, colons, and brackets inside message labels can confuse the parser. Wrap problematic labels in quotes if needed.
• Overloading one diagram: If your diagram has 15 participants and 60 messages, it becomes unreadable. Split complex flows into smaller diagrams.
• Inconsistent naming: If you declare participant API but later reference Api, Mermaid treats them as different participants. Keep names consistent.

You can find more practical diagram code patterns in this collection of Mermaid code examples for software documentation.

How do you render a Mermaid sequence diagram?

You have several options depending on where you work:

• GitHub and GitLab: Wrap your code in a mermaid fenced code block and it renders automatically in issues, PRs, and Markdown files.
• Online editor: Use the official Mermaid Live Editor to paste your code and see the diagram instantly.
• VS Code: Install the Mermaid extension to preview diagrams right in your editor.
• Documentation sites: Tools like Docusaurus, MkDocs, and VitePress support Mermaid out of the box or through plugins.

What should I practice next?

Once you're comfortable with the basics, try building diagrams for real scenarios in your own projects. Map out an API flow from a service you use. Document the signup process for your app. Diagram how your frontend talks to your backend.

The more you use sequence diagrams in actual documentation, the more natural the syntax becomes. You can also explore more sequence diagram features and patterns as you get comfortable with the fundamentals.

Quick-start checklist for your first sequence diagram

1. Start with sequenceDiagram on the first line
2. Declare your participants with clear names or aliases
3. Use ->> for requests and -->> for responses
4. Add Note blocks to explain anything that isn't obvious from the message label
5. Use alt/else for conditional flows and loop for repeated actions
6. Add autonumber if you have more than five steps
7. Test your diagram in the Mermaid Live Editor before committing it
8. Keep diagrams focused split complex flows into multiple diagrams when needed

Tip: Start small. Write a three-step interaction between two participants, render it, and then expand. Building diagrams incrementally catches syntax errors early and keeps your documentation accurate.