Mermaid Sequence Diagram Tutorial (With Syntax)

A sequence diagram shows how different participants - users, services, systems - interact over time, with messages passing between them in order. It is one of the most useful diagrams in software design because it makes the choreography of a system concrete: who calls whom, in what order, and what comes back. Mermaid's sequence diagram syntax is particularly clean, and once you know it you can capture an interaction in the time it takes to describe it in words.

This tutorial builds a sequence diagram step by step, introducing each syntax feature with a small, correct snippet you can copy. We will cover participants, the different message arrow types, activations, loops and conditionals, and notes. By the end you will be able to read and write real sequence diagrams. You can try every snippet live in the editor at /diagram-tools/mermaid-editor, or explore the dedicated sequence tooling at /diagram-tools/sequence-diagram.

Participants and the first message

Every sequence diagram starts with the declaration `sequenceDiagram` on its own line. Below that, you describe interactions. The simplest possible diagram is a single message between two participants: `Alice->>John: Hello John`. That one line creates two participants, Alice and John, draws a vertical lifeline for each, and shows a solid arrow carrying the message "Hello John" from Alice to John. Mermaid infers the participants from the messages, so you often do not need to declare them separately.

You can declare participants explicitly if you want to control their order or give them aliases. Writing `participant A as Alice` lets you refer to the participant as `A` in messages while displaying "Alice" in the diagram, which keeps long message lines readable. Declaring participants up front also fixes the left-to-right order they appear in, rather than letting Mermaid order them by first appearance - useful when you want a specific arrangement.

Message arrow types

Mermaid distinguishes several kinds of messages through the arrow syntax, and using the right one communicates intent. A solid arrow with a filled head, written `->>`, is a synchronous call - the sender waits for a response. A dashed arrow, written `-->>`, is typically a response or return message. These two are the workhorses: `Alice->>John: Ask question` followed by `John-->>Alice: Give answer` reads as a request and its reply.

• `->>` solid line with arrowhead: a synchronous call or request.
• `-->>` dashed line with arrowhead: a response or return message.
• `->` solid line without arrowhead: a simple signal or asynchronous message.
• `-->` dashed line without arrowhead: an async response or a weaker relationship.
• `-x` solid line ending in a cross: a message that is lost or fails.
• `-)` solid line with an open arrowhead: an asynchronous message (fire-and-forget).
• The text after the colon is always the message label describing what is being communicated.

Activations, loops, and conditionals

Activations show when a participant is actively processing. You turn one on and off by appending `+` and `-` to messages: `Alice->>+John: Request` activates John's lifeline (drawn as a thin bar), and `John-->>-Alice: Response` deactivates it. The activation bar makes it visually clear how long John is busy handling the request, which matters in diagrams with nested calls where you want to see how deep the call stack goes.

For repetition and branching, Mermaid provides block constructs. A `loop` block repeats a set of messages: you write `loop Every minute`, then the messages inside, then `end`. Conditionals use `alt` and `else`: `alt Payment valid` for one branch, `else Payment declined` for the other, closed with `end`. There is also `opt` for an optional block that may or may not happen, and `par` for messages that occur in parallel. These blocks draw labelled frames around the relevant messages, so the control flow of the interaction is visible at a glance.

Notes and grouping

Notes add explanatory text to a diagram. You place a note over a participant or spanning several with syntax like `Note over Alice: She is thinking` or `Note over Alice,John: They negotiate`. Notes are invaluable for annotating why something happens, not just what - a message shows the call, and a note can explain the business rule behind it. You can also position a note to the left or right of a participant with `Note left of` and `Note right of`.

For larger diagrams, you can group participants into boxes to show they belong to the same system or team, and use dividers to mark phases of the interaction. As with all Mermaid, the layout is automatic - you never position a lifeline or route a message by hand, you just declare the interaction and Mermaid draws it cleanly. When your sequence diagram grows complex or you want to fine-tune its appearance for a presentation, you can bring it into the visual canvas at /diagrams, or keep iterating in the live Mermaid editor at /diagram-tools/mermaid-editor where you see the rendered result update as you type.