Mermaid sequence diagrams

A sequence diagram shows who talks to whom, and in which order. Time runs from top to bottom. Each participant gets a vertical line, and each message is an arrow between two lines. Mermaid lets you write this as plain text inside a Markdown file. This page covers participants, arrows, activations, control blocks and notes.

The smallest sequence diagram

Start a fenced code block marked mermaid, then write sequenceDiagram on the first line. Each following line is one message.

sequenceDiagram
    Alice->>Bob: Hi Bob, are you there?
    Bob-->>Alice: Yes, I am here.

The format is Sender, an arrow, Receiver, a colon, then the message text.

Participants and actors

Mermaid creates participants as they appear. To control the order from left to right, declare them first. Use actor instead of participant to draw a stick figure. Use as to give a short ID a longer display name.

sequenceDiagram
    actor U as User
    participant App as Mac app
    participant FS as File system
    U->>App: Open notes.md
    App->>FS: Read file
    FS-->>App: File contents
    App-->>U: Formatted document

Short IDs keep the message lines easy to type. The display names are what readers see. Participants appear from left to right in the order you declare them. Put the one who starts the conversation on the left, so most requests point right and most replies point left.

Arrow types

The arrow tells the reader what kind of message it is.

sequenceDiagram
    participant A
    participant B
    A->>B: Solid line, arrowhead
    B-->>A: Dotted line, arrowhead
    A->B: Solid line, no arrowhead
    B-->A: Dotted line, no arrowhead
    A-xB: Solid line, cross at the end
    B--xA: Dotted line, cross at the end
    A-)B: Solid line, open arrow (async)

A common pattern is ->> for a request and -->> for its reply. The cross shows a message that fails or is lost. The open arrow -) marks an asynchronous message, one the sender does not wait on.

Activations

An activation is a thin bar on a participant’s line. It shows when that participant is busy. You can write activate and deactivate lines, or use the shorter + and - signs on the arrows.

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database
    C->>+S: GET /notes
    S->>+DB: Query notes
    DB-->>-S: Rows
    S-->>-C: 200 OK

+ after the arrow activates the receiver. - deactivates the sender of the reply. Activations can stack when the same participant is called again.

Loops, alternatives and options

Blocks group messages and add simple logic. Every block ends with end.

• loop repeats the messages inside.
• alt and else show two or more alternative paths.
• opt shows a step that only happens sometimes.

sequenceDiagram
    participant V as Viewer
    participant F as File
    loop Every time the file changes
        F->>V: Change event
        V->>F: Read new contents
        alt File can be parsed
            V->>V: Render document
        else Parsing fails
            V->>V: Keep last good view
        end
    end
    opt User presses Print
        V->>V: Open print dialog
    end

Blocks can be nested, as above. The text after the keyword is the label shown on the block. Mermaid also has par for parallel messages, critical for steps that must happen, and break for an early exit.

Notes

Notes add short explanations next to or across participants.

sequenceDiagram
    participant A as Agent
    participant M as Markdown file
    Note right of A: Writes a plan
    A->>M: Save plan.md
    Note over A,M: The file is the only shared state

Use left of, right of or over. A note over two participants spans both lines. Notes are good for state, assumptions and reasons, the things an arrow cannot say. Keep them short. If a note needs several sentences, it belongs in the text around the diagram.

Numbering and grouping

Add autonumber to number every message. This helps when you refer to steps in the text around the diagram.

sequenceDiagram
    autonumber
    box Local machine
        participant E as Editor
        participant F as File
    end
    participant R as Remote repo
    E->>F: Save
    F->>R: Push
    R-->>F: Pull

box draws a frame around a group of participants. Close it with end, like every other block.

Tips for clear sequence diagrams

• Keep to the main path first. Add error cases with alt only where they matter.
• Use short IDs and readable display names.
• Keep message text short. Two to five words is often enough.
• Split long flows into several diagrams, one per scenario.

Viewing sequence diagrams on a Mac

The Mermaid source stays readable in any text editor. To see the drawn diagram you need a tool that renders Mermaid, such as GitHub, an editor preview, or a Markdown viewer. Markko Pro renders Mermaid diagrams in its window and in Quick Look, and it reloads the view when the file changes.

For every option, see the sequence diagram page of the official Mermaid documentation at mermaid.js.org.

FAQ

Related