How to Create Sequence Diagrams in Mermaid Markdown

If you've ever needed to show how different parts of a system communicate with each other who calls whom, in what order, and what gets sent back a sequence diagram is the tool for the job. Writing them in Mermaid markdown makes the process faster because you describe the diagram in plain text instead of dragging boxes around in a visual editor. This matters because sequence diagrams help developers, architects, and technical writers explain interactions clearly in documentation, pull requests, and wikis without leaving their code editor.

What is a Mermaid sequence diagram?

A Mermaid sequence diagram is a text-based diagram that shows how objects or actors interact over time. You write simple markdown-like syntax, and Mermaid renders it into a visual diagram with lifelines, messages, and activations. The official Mermaid sequence diagram documentation covers every supported keyword, but you only need a handful to get started.

Each diagram has a few core parts:

Participants the actors, services, or objects involved in the interaction.
Messages arrows showing communication between participants, labeled with what's being sent or called.
Lifelines the vertical dashed lines that represent each participant's existence over time.
Activations the thin boxes on a lifeline showing when a participant is actively processing something.

How do I write my first sequence diagram in Mermaid?

Start with the sequenceDiagram keyword, declare your participants, and then define the messages between them. Here's a basic example showing a user logging in:

sequenceDiagram participant User participant Browser participant Server User->>Browser: Enter credentials Browser->>Server: POST /login Server-->>Browser: 200 OK + token Browser-->>User: Show dashboard

The ->> arrow draws a solid line (a request), and -->> draws a dashed line (a response). That single convention covers most of what you need.



What arrow types does Mermaid support for sequence diagrams?

Mermaid gives you several arrow styles to represent different kinds of interaction:


->> solid line with an open arrowhead (asynchronous message or request)
-->>  dashed line with an open arrowhead (response)
-> solid line with a filled arrowhead (synchronous message)
--> dashed line with a filled arrowhead (dashed synchronous)
-x solid line ending with a cross (message that fails or is lost)
o-> solid line with a circle at the start (async signal)


These distinctions matter when you're documenting real systems. A synchronous call blocks the caller, while an asynchronous message doesn't. Picking the right arrow makes your diagram accurate.

How do I show a participant processing a request?

Use the activate and deactivate keywords to draw activation boxes on a lifeline. These show when a participant is actively handling something useful for clarifying processing time or nested calls.

sequenceDiagram

  Client->>+API: GET /users

  API->>+Database: SELECT FROM users

  Database-->>-API: Result set

  API-->>-Client: JSON response

The + after the arrow shorthand is a compact way to activate a participant inline. The - deactivates it. This is cleaner than separate activate/deactivate lines when each message triggers one activation.

How do I add notes and conditions to my sequence diagram?

Notes let you add context without cluttering the message flow. Place them over a single participant or spanning two:

Note right of Server: Validate JWT token

Note over Client,Server: TLS handshake happens here

For conditional logic, use alt/else/end blocks:

alt Valid credentials

  Server-->>Browser: 200 OK

else Invalid credentials

  Server-->>Browser: 401 Unauthorized

end

You can also use opt for optional steps, loop for repeated actions, and par for parallel interactions. These control structures are what make Mermaid sequence diagrams expressive enough for real-world workflows.

Can I use loops and parallel blocks in sequence diagrams?

Yes. Wrap messages in block keywords to show repetition or concurrency:

loop Every 30 seconds

  Client->>Server: Poll for updates

  Server-->>Client: No changes

end

For parallel operations:

par Send email notification

  Server->>EmailService: Send email

and Send SMS notification

  Server->>SMSService: Send SMS

end

These blocks nest cleanly and render as labeled regions in the diagram.

How do I style or rearrange participants in Mermaid?

Mermaid usually auto-arranges participants in the order they first appear. You can override this by explicitly declaring them with the participant keyword at the top of the diagram. The order you list them sets the left-to-right position.

For styling, you can use the rect keyword to shade a region of the diagram helpful for highlighting a specific phase or grouping:

rect rgb(200, 230, 255)

  Note over Client,Server: Authentication phase

  Client->>Server: Login request

  Server-->>Client: Auth token

end

Mermaid also supports themes. If you're embedding diagrams in a site, check out our Mermaid syntax cheat sheet for tips on styling across diagram types.

How do I add message numbering and autonumber?

Put autonumber at the start of your diagram (after sequenceDiagram) and every message arrow gets a sequential number. This is helpful when referencing steps in written documentation or reviews.

sequenceDiagram

  autonumber

  Client->>Server: Request

  Server->>Database: Query

  Database-->>Server: Data

  Server-->>Client: Response

What are the most common mistakes when writing Mermaid sequence diagrams?

After working with Mermaid for a while, these errors come up again and again:


Forgetting to close blocks. Every alt, loop, par, opt, and rect needs a matching end. Miss one and the whole diagram breaks.
Using undefined participants. If you reference a participant in a message before declaring or using it, Mermaid may render it in unexpected order.
Mismatched arrow syntax. A small typo in an arrow (>> vs >>) can cause rendering errors. Stick to the documented patterns.
Overloading a single diagram. If your sequence has more than 15–20 messages, it becomes hard to read. Split it into smaller, focused diagrams instead.
Ignoring activation boxes. Without them, nested calls and concurrent processing are hard to follow.


Where can I preview and test my Mermaid sequence diagrams?

The easiest way to test your diagrams is with the Mermaid live editors and online tools compared in our tool roundup. The official Mermaid Live Editor at mermaid.live gives you a split-pane view: write on the left, see the rendered diagram on the right.

Most modern documentation platforms also support Mermaid natively. GitHub renders Mermaid fenced code blocks in markdown files and pull request comments. GitLab, Notion, Obsidian, and Confluence (with plugins) do too. This means your sequence diagrams stay version-controlled alongside your code.

How does a sequence diagram differ from other Mermaid diagrams?

Sequence diagrams focus on time-based interactions between participants. If you need to show system states and transitions instead, use a Mermaid state diagram. If you need to show a process flow or decision tree, a flowchart is a better fit our flowchart syntax cheat sheet covers that. Pick the diagram type that matches what you're trying to communicate.

Quick checklist before publishing your sequence diagram


All alt, loop, opt, par, and rect blocks have matching end statements.
Participants are declared in the order you want them displayed left to right.
Arrow types accurately reflect the type of communication (sync, async, response).
Activation boxes are used where nesting or active processing occurs.
The diagram has fewer than 20 messages split larger flows into separate diagrams.
Notes are used sparingly and add real context, not noise.
You tested the diagram in a live editor before committing it.


Next step: Take one real interaction from your current project a login flow, an API call chain, a webhook process and write it as a Mermaid sequence diagram right now. Paste it into the Mermaid Live Editor, fix any syntax errors, and drop it into your documentation. One diagram that matches your actual codebase is more useful than ten hypothetical examples.