If you've ever tried to document how different parts of a system talk to each other, you know it can get messy fast. That's where Mermaid sequence diagrams come in and having a solid cheatsheet of commands at your fingertips saves you from constantly Googling syntax while you work. This reference covers every Mermaid sequence diagram command you're likely to need, organized so you can find what you're looking for quickly.

What Is a Mermaid Sequence Diagram?

A Mermaid sequence diagram is a text-based diagram that shows how objects or participants interact over time through messages. Instead of dragging boxes and arrows in a visual editor, you write short lines of code that Mermaid renders into a clean diagram. The syntax lives inside a sequenceDiagram block and uses simple keywords to define participants, messages, loops, conditions, and more.

Because it's plain text, you can version-control it, embed it in Markdown files, and keep it alongside your source code. Developers, technical writers, and architects use it to map out API flows, authentication sequences, microservice communication, and other multi-step interactions. If you want a deeper look at how these diagrams fit into software architecture, check out sequence diagram code examples for software architecture.

How Do You Start a Mermaid Sequence Diagram?

Every diagram begins with the sequenceDiagram keyword. Everything that describes your diagram goes inside that block. Here's the skeleton:

  • sequenceDiagram opens and closes the diagram block
  • participant declares each actor or system in the diagram
  • actor like participant, but renders as a person-shaped figure

Declaring participants explicitly lets you control the order they appear in the diagram. If you skip declarations, Mermaid creates them automatically as messages reference them but the left-to-right order may not match what you want.

Basic Participant Example

  • participant User
  • participant Server
  • participant Database
  • actor Admin

What Commands Send Messages Between Participants?

Messages are the core of any sequence diagram. In Mermaid, you use arrow syntax to define who sends what to whom, and whether a response is expected.

Solid Arrow (Synchronous Message)

  • A->>B: Request data solid line with a filled arrowhead

Dashed Arrow (Asynchronous or Response)

  • B-->>A: Return data dashed line with a filled arrowhead
  • A->>B: Open solid line, open arrowhead (no > after the second -)

A common mistake is mixing up the arrow types. Use solid arrows for requests and dashed arrows for responses to keep your diagrams readable. If you want a full breakdown of message types and when to use each one, see UML sequence diagram message types and notation.

Activation and Deactivation

  • activate B shows a thin activation bar on participant B (meaning it's processing)
  • deactivate B removes the bar

You can also use the shorthand by adding + and - directly to a message line:

  • A->>+B: Call function sends message and activates B
  • B-->>-A: Done responds and deactivates B

How Do You Add Notes and Annotations?

Notes help explain what's happening at specific points. Mermaid gives you a few options:

  • Note right of B: Processing request note attached to one participant
  • Note left of A: Waiting
  • Note over A,B: Shared context note spanning across two participants

Notes are short by default. If your note text is long, Mermaid will wrap it, but keeping notes brief improves readability.

What Commands Handle Loops and Conditions?

Real interactions rarely follow a straight line. Mermaid provides keywords for control flow structures that make your diagrams accurate.

Loops

  • loop Every 30 seconds ... end

Conditions (Alt/Else)

  • alt Success ... else Failure ... end

Optional Blocks

  • opt Optional step ... end

Parallel Execution

  • par Action A ... and Action B ... end

Critical Section

  • critical Must complete ... option Alternative ... end

Break

  • break Something went wrong ... end

A frequent mistake is forgetting the end keyword. Every block structure loop, alt, opt, par, critical, break needs a matching end, just like curly braces in code.

How Do You Use Loops Inside Conditions?

You can nest these blocks inside each other. For example, an alt block inside a loop:

  • loop Retry up to 3 times
  •   alt Connection available
  •     A->>B: Send
  •   else Timeout
  •     Note over A: Wait
  •   end
  • end

Indentation isn't required by Mermaid, but it makes nested structures much easier to read when you're editing the source text.

Can You Add Titles and Backgrounds?

Yes. These optional commands improve presentation:

  • title My Sequence Diagram adds a title above the diagram
  • rect rgb(200, 220, 255) ... end highlights a section with a colored background

Background rectangles are useful for visually grouping related steps, like marking a "setup phase" versus a "runtime phase."

What About Aliases, Links, and Comments?

Mermaid supports a few more commands that help with complex diagrams:

  • participant A as Alice alias, so A is short to type but "Alice" appears in the diagram
  • link A: Dashboard @ https://example.com clickable link on a participant
  • A->>B: msg @_self opens link in same tab
  • %% This is a comment ignored by the renderer

Common Mistakes That Break Mermaid Sequence Diagrams

Most rendering errors come from a few predictable issues:

  • Missing end keyword for a block Mermaid won't render the diagram at all
  • Wrong arrow syntax using -> instead of ->> or -->>>
  • Special characters in message text colons, hashes, and brackets may need escaping or quoting
  • Using keywords as participant names words like end, loop, or note as a participant ID will confuse the parser
  • Forgetting the colon after the arrow A->>B message is invalid; it must be A->>B: message

If you've worked with other diagramming tools and are comparing approaches, PlantUML has its own syntax that's worth understanding too. Here's a breakdown of PlantUML sequence diagram commands for comparison.

Quick Reference: All Mermaid Sequence Diagram Commands

Here's the full cheatsheet in one place for easy scanning:

  1. sequenceDiagram open/close the diagram
  2. participant X / actor X declare a participant
  3. X->>Y: msg solid arrow, filled head
  4. X-->>Y: msg dashed arrow, filled head
  5. X->Y: msg solid arrow, open head
  6. X-->Y: msg dashed arrow, open head
  7. activate X / deactivate X show/hide activation bar
  8. Note left of X / Note right of X / Note over X,Y add notes
  9. loop ... end repeat block
  10. alt ... else ... end conditional branches
  11. opt ... end optional block
  12. par ... and ... end parallel actions
  13. critical ... option ... end critical section
  14. break ... end break out of a block
  15. title diagram title
  16. rect rgb(r,g,b) ... end colored background region
  17. participant A as Alias participant alias
  18. link / links add clickable links to participants
  19. %% comment source comment

You can find the official documentation at mermaid.js.org.

Your Next Step

Copy one of the examples from this cheatsheet into your Markdown editor, a Mermaid Live Editor, or your project's documentation and run it. Then start swapping in your own participants and messages. The fastest way to learn Mermaid sequence diagram commands is to build a real diagram for something you're actually working on a login flow, a webhook process, or a service-to-service call. Start with the skeleton, add your participants, write your first message, and build from there.