Mermaid Sequence Diagram Syntax: Every Feature, Explained with Examples

Mermaid sequence diagram syntax lets you create professional UML sequence diagrams from plain text. Instead of dragging boxes in Visio or Lucidchart, you type Alice->>Bob: Hello and the diagram renders itself. This guide covers every syntax feature with copy-paste examples you can try right now in our free sequence diagram maker.

If you already know the basics and just need a quick lookup, jump to the cheat sheet table. Otherwise, read through from participants to parallel blocks and you will have the full syntax memorized in about ten minutes.

Defining Participants and Actors

Every sequence diagram starts with sequenceDiagram on the first line. After that, you can declare participants explicitly or let Mermaid create them from your first message reference.

Explicit declaration controls the order participants appear left-to-right:

sequenceDiagram
    participant Client
    participant API
    participant Database

Use actor instead of participant to render a stick figure icon instead of a box. This is useful for human users:

sequenceDiagram
    actor User
    participant Browser
    participant Server

If you skip declarations, Mermaid creates participants in the order they first appear in messages. For simple diagrams that works fine, but explicit declaration gives you control over layout.

You can also use aliases to keep your code short while displaying longer names:

sequenceDiagram
    participant FE as Frontend App
    participant BE as Backend Service
    FE->>BE: GET /users

The alias (FE) is what you type in messages. The full name (Frontend App) is what shows up in the diagram.

Arrow Types: Solid, Dashed, Async, and Cross

Mermaid supports six arrow types for different message semantics. Here is what each one means and when to use it:

Syntax	Arrow	Use For
->>	Solid line, filled arrow	Synchronous request (most common)
-->>	Dashed line, filled arrow	Response / return value
->>	Solid line, open arrow	Async fire-and-forget
-->>	Dashed line, open arrow	Async response
-x	Solid line with cross	Failed / rejected message
--x	Dashed line with cross	Failed response

A typical request-response pair looks like this:

Browser->>Server: POST /login
Server-->>Browser: 200 OK + JWT

Self-calls (when a participant sends a message to itself) work too. They show up as a loop-back arrow on the same lifeline:

Server->>Server: Validate token

This is one area where text-based tools shine over drag-and-drop editors. You define the intent (-->> = response), and the tool handles the visual rendering. No manual arrow routing needed. If you are working with flowchart symbols as well, the arrow conventions differ slightly since flowcharts use diamond shapes for decisions instead of alt blocks.

Control Flow: Loop, Alt, Opt, and Par

These four combined fragment blocks cover most real-world control flow scenarios. Each one wraps a section of messages in a labeled box.

Loop shows repeated messages:

loop Every 30 seconds
    Client->>Server: Health check ping
    Server-->>Client: 200 OK
end

Alt/Else shows conditional branching. This is the if-else of sequence diagrams:

alt User exists
    Server-->>Client: 200 User data
else User not found
    Server-->>Client: 404 Not found
end

Opt is like alt but with only one branch. Use it for optional behavior that may or may not happen:

opt Has cached response
    Browser-->>User: Show cached data
end

Par shows parallel execution. Two or more things happening simultaneously:

par Send notifications
    Server->>EmailService: Send email
and
    Server->>PushService: Send push
end

You can nest these blocks inside each other. An alt inside a loop, or a par inside an alt branch. Mermaid handles the rendering. Just make sure every block has a matching end. If you get a syntax error, the most common cause is a missing end keyword. Our sequence diagram tool highlights syntax errors instantly so you catch these fast.

These same concepts apply across UML diagram types. If you are comparing when to use sequence diagrams versus other diagram types, we covered that in our class diagram vs sequence diagram comparison.

Sell Custom Apparel — We Handle Printing & Free Shipping

Notes, Activation Bars, and Auto-Numbering

Notes add annotations to your diagram. They can appear to the right, left, or spanning multiple participants:

Note right of Server: Validates JWT
Note over Client,Server: TLS encrypted
Note left of Database: Read replica

Multiline notes use the Note over syntax. They are useful for documenting assumptions or constraints that do not fit in a message label.

Activation bars show when a participant is actively processing. They render as a narrow rectangle on the lifeline:

Client->>+Server: POST /order
Server->>+Database: INSERT order
Database-->>-Server: Order ID
Server-->>-Client: 201 Created

The + before the participant activates it, and - deactivates it. You can also use the explicit activate and deactivate keywords if you prefer readability over brevity.

Auto-numbering adds sequential numbers to each message. Just add autonumber right after sequenceDiagram:

sequenceDiagram
    autonumber
    Client->>Server: Request
    Server-->>Client: Response

This is particularly useful for walkthrough documentation where you are referencing step numbers in a separate write-up. Rather than manually numbering messages (and re-numbering when you insert a new step), the tool handles it automatically.

Mermaid Sequence Diagram Cheat Sheet

Bookmark this table. It covers every feature in one place:

Feature	Syntax	Example
Participant	participant Name	participant API
Actor (person)	actor Name	actor User
Alias	participant X as Full Name	participant FE as Frontend
Sync message	A->>B: text	Client->>Server: GET /data
Response	A-->>B: text	Server-->>Client: 200 OK
Self-call	A->>A: text	Server->>Server: Validate
Loop	loop Label ... end	loop Every 5s ... end
Alt/Else	alt Label ... else Label ... end	If-else branching
Opt	opt Label ... end	Optional path
Par	par Label ... and ... end	Parallel execution
Note	Note right/left/over	Note over A,B: text
Activate	+ / activate	A->>+B: Start
Deactivate	- / deactivate	B-->>-A: Done
Autonumber	autonumber	Adds 1, 2, 3 to messages

Every feature listed above works in our free browser-based tool. Paste the syntax, hit render, export as PNG or SVG. For related syntax references, check out our Mermaid ER diagram syntax guide or the Mermaid flowchart editor.

Troubleshooting: Common Mermaid Syntax Errors

Mermaid sequence diagrams are straightforward, but a few mistakes trip up everyone at least once:

"Parse error" on the first line. Make sure the first line is exactly sequenceDiagram with no extra spaces or characters before it. It is case-sensitive.

Missing end keyword. Every loop, alt, opt, and par block needs a matching end. If you have nested blocks, count your end keywords. Three opens means three ends.

Using the wrong arrow syntax. Common confusion: -> (single arrow, open) versus ->> (double arrow, filled). The double-arrow version is what you want for standard synchronous messages.

Special characters in message labels. Colons inside message text can confuse the parser. If your message text contains a colon, sometimes wrapping it differently or simplifying the label helps.

Participant names with spaces. If a participant name has spaces, use the alias syntax: participant WS as Web Server. Referencing Web Server directly in messages without an alias will break.

Our tool gives you instant error feedback. If something is wrong, you see the error message immediately below the editor. Fix the syntax, and the preview updates live. No separate compile step, no waiting.

Frequently Asked Questions

What is Mermaid sequence diagram syntax?

Mermaid is a text-based diagramming language that lets you create sequence diagrams by typing simple code. You define participants and messages with arrow syntax like Alice->>Bob: Hello, and the diagram renders automatically. It works in GitHub, GitLab, Notion, VS Code, and browser-based tools like WildandFree.

How do I add if-else conditions to a Mermaid sequence diagram?

Use the alt/else block. Write alt Condition on one line, add your messages, then else Other condition, more messages, and end. This renders as a labeled box showing both branches of the conditional flow.

Can I create parallel flows in Mermaid sequence diagrams?

Yes. Use the par block. Write par Label, add messages for the first parallel track, then and to start the second track, and end to close the block. Both tracks render side by side in the diagram.

How do I export a Mermaid sequence diagram as an image?

In our free browser tool, click Export PNG for a raster image or Export SVG for a scalable vector. SVG is better for documentation since it stays sharp at any zoom level. Both options download instantly with no watermark.