Mermaid Sequence Diagram Syntax Reference Guide

If you've ever needed to show how different parts of a system communicate with each other over time, a sequence diagram is one of the clearest ways to do it. Mermaid lets you create these diagrams using plain text, so you can version-control them, embed them in documentation, and edit them without any drag-and-drop tools. This reference guide covers the full syntax for Mermaid sequence diagrams from basic message arrows to advanced features like loops, alt blocks, and activation bars so you can write accurate diagrams quickly.

What Is a Mermaid Sequence Diagram?

A Mermaid sequence diagram is a text-based diagram that shows interactions between participants (objects, users, services, or systems) arranged in a timeline. You write simple markup, and Mermaid renders it as a visual diagram. The left-to-right ordering of participants follows the order you define them, and messages flow between them vertically to show the sequence of events.

You don't need a separate tool or drawing application. If your platform supports Mermaid like GitHub, GitLab, Notion, or a Markdown file with the right parser you just write the code and the diagram appears. For a broader overview of how Mermaid works with Markdown, see how to create Mermaid diagrams in Markdown.

How Do You Start a Sequence Diagram?

Every Mermaid sequence diagram begins with the sequenceDiagram keyword. After that, you define participants and messages. Here's the simplest possible example:

sequenceDiagram
 Alice->>Bob: Hello, Bob!
 Bob-->>Alice: Hi, Alice!

This creates two participants (Alice and Bob) and shows a solid arrow from Alice to Bob, then a dashed arrow back from Bob to Alice.

How Do You Define Participants?

Participants are the columns in your diagram. You can declare them explicitly or let Mermaid create them automatically when they first appear in a message.

Explicit Declaration

Use the participant keyword to define and order your participants:

sequenceDiagram
 participant Client
 participant Server
 participant Database

Explicit declaration gives you control over the display order, even if messages don't follow that order.

Aliases

You can give participants short aliases so your message lines stay readable:

sequenceDiagram
 participant U as User
 participant A as API Gateway
 participant S as Auth Service
 U->>A: Login request
 A->>S: Validate token
 S-->>A: Token valid
 A-->>U: 200 OK

The alias appears in message definitions, while the full name appears in the diagram box.

Actor vs. Participant

Use actor instead of participant if you want a person-shaped icon rather than a box:

sequenceDiagram
 actor User
 participant Server
 User->>Server: Send request

What Message Types Are Available?

Mermaid supports several arrow styles to represent different kinds of communication. This is one of the most referenced parts of any sequence diagram syntax guide:

Solid arrow with open head: A->>B: message a solid line with a filled arrowhead (synchronous call)
Dashed arrow with open head: A-->>B: message a dashed line with a filled arrowhead (response or return)
Solid arrow with cross head: A-xB: message a solid line with an X (indicates a lost or failed message; note: no space before x)
Dashed arrow with cross head: A--xB: message a dashed line with an X
Solid arrow with open head (no space): A->B: message a solid line with an open arrowhead (asynchronous)
Dashed line, no arrowhead: A--B: message a dashed line with no arrow (a link or reference)

A common mistake is mixing up ->> and -->> . If you want a response or return message, use the double dash (-->> ). For a full cheat sheet of Mermaid syntax patterns, check this Mermaid syntax cheat sheet.

How Do You Add Notes?

Notes let you annotate messages or add context to specific participants. There are three placement options:

sequenceDiagram
 participant A
 participant B
 Note over A: Single participant note
 Note over A,B: Note spanning both
 A->>B: Request
 Note right of B: Processing the request

Note over A,B places a note that stretches across both participants. This is helpful when explaining an interaction that involves multiple parties.

How Do Loops Work in a Sequence Diagram?

If a set of messages repeats, wrap them in a loop block:

sequenceDiagram
 Client->>Server: Poll for updates
 loop Every 30 seconds
 Client->>Server: GET /status
 Server-->>Client: 200 OK
 end

The label inside the loop keyword (here, "Every 30 seconds") appears in the diagram's box.

How Do You Show Conditions and Alternatives?

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

sequenceDiagram
 Client->>Server: Login
 alt Credentials valid
 Server-->>Client: 200 OK
 else Credentials invalid
 Server-->>Client: 401 Unauthorized
 end
 opt User has 2FA enabled
 Client->>Server: Send 2FA code
 end

You can also use else multiple times to show more than two branches. For another condition-based diagram type, see these Mermaid flowchart code examples.

Other Blocks: Parallel and Break

par shows actions happening at the same time:

sequenceDiagram
 par Send email
 Server->>EmailService: Notify user
 and Send SMS
 Server->>SMSService: Notify user
 end

break indicates a stop in the flow due to an exception:

sequenceDiagram
 Client->>Server: Fetch data
 break On timeout
 Server-->>Client: 504 Gateway Timeout
 end

What Are Activation Bars?

Activation bars (also called focus bars) show when a participant is actively processing a request. You control them with activate and deactivate:

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

The + and - shorthand is a faster alternative to separate activate/deactivate lines. The + goes after the arrow on the receiving participant; the - goes after the arrow on the sending participant.

How Do You Set a Diagram Title?

Add a title with the title keyword:

sequenceDiagram
 title User Authentication Flow
 actor User
 participant App
 participant Auth
 User->>App: Enter credentials
 App->>Auth: Validate

Can You Group Messages?

Yes. Use rect to draw a colored background rectangle around a section of your diagram:

sequenceDiagram
 participant A
 participant B
 rect rgb(200, 220, 255)
 A->>B: Step 1
 B-->>A: Ack
 A->>B: Step 2
 end

This is useful for visually separating phases like "authentication" from "data processing."

What About Comments and Line Breaks?

Add comments with %% they won't appear in the rendered diagram:

sequenceDiagram
 %% This is a comment
 A->>B: Hello

For multi-line message text, use inside the message label:

sequenceDiagram
 A->>B: Line one
Line two

What Common Mistakes Break Sequence Diagrams?

Missing end keyword every loop, alt, opt, par, break, and rect block needs a closing end.
Wrong arrow syntax using -> when you mean ->>, or forgetting the space before the message text.
Undeclared participants in aliases if you use an alias in a message, define the participant with participant X as Label first, or Mermaid may create an extra box.
Not using activate/deactivate correctly each + needs a matching -, or the activation bars won't render as expected.
Special characters in messages characters like #, ;, or {} can confuse the parser. Keep labels simple or escape them.

Practical Example: A Full API Request Flow

Here's a realistic diagram that combines several features:

sequenceDiagram
 title API Request with Authentication
 actor User
 participant Client as Mobile App
 participant API as API Server
 participant Auth as Auth Service
 participant DB as Database

 User->>Client: Tap "Load Data"
 activate Client
 Client->>+API: GET /data (Bearer token)
 API->>+Auth: Validate token
 alt Token valid
 Auth-->>-API: User ID
 API->>+DB: SELECT FROM data
 DB-->>-API: Result set
 API-->>-Client: 200 JSON
 else Token expired
 Auth-->>-API: 401
 API-->>Client: 401 Unauthorized
 Client->>User: Show login screen
 end
 deactivate Client

This shows participants with aliases, nested alt/else blocks, activation bars, and a clear title all features covered in this reference.

Quick Reference: All Key Keywords

Keyword	Purpose
`sequenceDiagram`	Starts the diagram
`participant` / `actor`	Declares a participant
`as`	Sets an alias
`->>` `-->>` `->` `--` `-x` `--x`	Message arrow styles
`Note over` / `Note right of` / `Note left of`	Adds a note
`loop` / `alt` / `else` / `opt` / `par` / `break`	Control flow blocks
`activate` / `deactivate`	Show processing time (focus bars)
`rect`	Colored background section
`title`	Diagram title
`end`	Closes a block
`%%`	Comment (not rendered)

For the official specification and additional syntax details, refer to the Mermaid.js sequence diagram documentation.

Next Step: Test It Right Now

Open the Mermaid Live Editor.
Paste any of the code examples above into the editor panel.
Try adding a new participant, changing an arrow type, or wrapping messages in a loop block.
Export the diagram as SVG or PNG and drop it into your documentation.
Save the source text in your repo so it stays version-controlled alongside your code.

Start with one diagram this week even a simple three-participant flow and you'll quickly get comfortable enough to document more complex interactions without a visual editor.