Skip to content
MermaidViewer

Software diagram

Mermaid sequence diagram

Mermaid sequence diagram syntax for participants, messages, activations, loops and alternatives, with examples you can edit.

By MermaidViewer editorsPublished Updated

Basic sequence diagram example

Basic sequence diagram example diagram
mermaid
sequenceDiagram
    autonumber
    actor U as User
    participant W as Web App
    participant A as Auth API
    participant D as Database
    U->>W: Submit login form
    W->>A: POST /login
    A->>D: Find user by email
    D-->>A: User record
    alt password valid
        A-->>W: 200 + session token
        W-->>U: Redirect to dashboard
    else invalid
        A-->>W: 401 Unauthorized
        W-->>U: Show error
    end
Open in the live editor

Sequence diagrams show the order in which participants exchange messages. They are the go-to diagram for API calls, authentication handshakes, microservice interactions and any flow where timing matters.

Mermaid sequence diagrams read almost like a script: each line is one message from one participant to another. Mermaid handles lifelines, arrow alignment and spacing, and you get blocks for loops, alternatives, optional steps and parallel work.

When to use a sequence diagram

  • Documenting REST and GraphQL API request/response flows
  • Explaining OAuth, SSO and other authentication handshakes
  • Designing event-driven and microservice interactions
  • Debugging race conditions by laying out message order

Sequence Diagram syntax reference

SyntaxWhat it does
sequenceDiagramStart a sequence diagram.
participant A as AliceDeclare a participant with an alias (controls order).
actor UDeclare a participant drawn as a stick figure.
A->>B: textSolid line with arrowhead (synchronous call).
A-->>B: textDotted line with arrowhead (response).
A-)B: textAsync message (open arrow).
A-xB: textMessage with a cross at the end (failure / lost).
activate A / deactivate A or A->>+B / B-->>-AShow an activation bar on the lifeline.
Note right of A: text / Note over A,B: textAdd notes beside or spanning participants.
loop / alt ... else / opt / par ... and / critical / breakControl-flow blocks, each closed with end.
rect rgb(240,248,255) ... endHighlight a region with a background color.
autonumberNumber every message automatically.

Sequence Diagram examples

Retry loop with activations

Activation bars (+ and -) show when a participant is busy; loop shows retries.

Retry loop with activations diagram
mermaid
sequenceDiagram
    participant C as Client
    participant S as Service
    participant Q as Queue
    C->>+S: Create job
    S->>Q: Enqueue
    loop Every 5s until done
        C->>S: GET /status
        S-->>C: pending
    end
    S-->>-C: completed
Open in the live editor

Parallel calls

par blocks show work happening at the same time.

Parallel calls diagram
mermaid
sequenceDiagram
    participant G as API Gateway
    participant U as Users
    participant O as Orders
    participant R as Recommendations
    G->>U: Get profile
    par fetch in parallel
        G->>O: Recent orders
    and
        G->>R: Suggestions
    end
    O-->>G: orders
    R-->>G: items
    Note over G: Merge and respond
Open in the live editor

A login form is a poor fit for a conversation. A mermaid sequence diagram earns its place when the reader has to see who calls whom, what comes back, and which branch runs when the answer is no. The syntax table covers the arrows. This section is about the order of the lifelines, the split between requests and replies, and one charge flow you can copy.

Order, arrows, and blocks

Declare every participant before the first message, in the left-to-right order you want on the page. The first time a name appears is the order Mermaid keeps. If the first message invents the cast, a service you mention late jumps to the right edge and the eye reads the story backwards.

Use a solid ->> for a request and a dotted -->> for a reply. That single habit makes a long chart scannable. When every arrow is solid, replies look like new work and a review turns into a guessing game.

autonumber stamps each message. A pull-request comment can then say "step 4" instead of quoting a label. Put it once, near the top. If you also type numbers into the message text, every line wears two numbers and the stamps stop helping.

alt and else are a fork, closed with end. loop and end are a repeat. They nest, and each block needs its own end. An else that never opened an alt is a parse error. The diagram is telling you the branch has no question.

Worked example

A shop charges a card through a pay service, and the pay service asks the bank. The bank either approves or declines. After that the shop polls status. Two poll arrows are enough to show the retry without drawing the whole timer.

Mermaid diagram
mermaid
sequenceDiagram
    autonumber
    participant Shop as Shop
    participant Pay as Pay
    participant Bank as Bank
    Shop->>Pay: Charge card
    Pay->>Bank: Authorize
    alt approved
        Bank-->>Pay: OK
        Pay-->>Shop: Paid
    else declined
        Bank-->>Pay: No
        Pay-->>Shop: Fail
    end
    loop status poll
        Shop->>Pay: Status
        Pay-->>Shop: Pending
    end
Open in the live editor

Shop, Pay, and Bank sit in call order. Step 1 is the shop's request. Step 2 is Pay handing the card to the bank. The alt splits the reply: a dotted OK becomes Paid, a dotted No becomes Fail. The loop sits after the decision, so a reader can see that polling is a separate habit, not a third outcome of the bank. If the poll should happen only while the charge is pending, say so in the loop title. The title is the only place that nuance fits without a paragraph on the arrow.

Keep message text short. "Authorize" is enough. The HTTP path and the error code belong in the doc under the diagram, or the arrow becomes a sentence and the lifelines get pushed apart.

When this is the wrong diagram

A flowchart is the better picture when the story is a policy of yes and no, and the actors don't matter. A state diagram is the better picture when one object sits in Draft, Review, and Live, and the arrows are events that move it. Reach for a sequence diagram when you would otherwise explain the feature by listing calls in order.

Common mistakes

  1. Leaving out the colon, as in Shop->>Pay Charge card. The parser wants Shop->>Pay: Charge card, and without the colon the line isn't a message.
  2. Opening alt or loop and forgetting end, or writing else when no alt is open. Both fail the parse, and the preview stops at that line.
  3. Letting the first message declare participants, then wondering why Bank sits on the left. Declare participant lines first, in the order the reader should meet them.
  4. Turning on autonumber and also typing "1." into the message text. Pick one numbering scheme so a review comment points at a single step.

Where to go next

The AI sequence diagram generator will draft the participants from a paragraph. Tighten the arrows in the editor, and keep the arrow forms on the cheat sheet. For a longer handshake, the OAuth sequence template shows the same blocks on an authorization code flow.

If you want the maker workflow rather than the token list, start with a free sequence diagram maker. Loops are in a sequence diagram with loop, forks are in sequence diagram alt, and the tool choice is sequence diagram software.

Tips and best practices

  • Declare participants up front to control their left-to-right order instead of relying on first mention.
  • Use solid arrows (->>) for requests and dotted arrows (-->>) for responses to make the flow scannable.
  • Turn on autonumber for diagrams that will be discussed in reviews so people can reference steps.
  • Keep messages short; push details into notes so the diagram stays readable.

Generate a sequence diagram with AI

Not sure where to start? Describe what you need and the AI sequence diagram generator writes the Mermaid code for you. Try prompts like:

  • “OAuth 2.0 authorization code flow with PKCE”
  • “Checkout with payment provider webhook confirmation”
  • “Chat message delivery with read receipts”

Sequence Diagram templates

Sequence Diagram FAQ

What arrow types does a Mermaid sequence diagram support?

Common ones are ->> (solid with arrowhead), -->> (dotted with arrowhead), -> and --> (no arrowhead), -x and --x (cross), and -) / --) for asynchronous messages.

How do I show if/else logic in a sequence diagram?

Use an alt block: alt condition, the messages, else other condition, more messages, and close with end. For a single optional branch use opt ... end.

Can participants be grouped?

Yes. Wrap participant declarations in box Title ... end (optionally with a color, e.g. box Aqua Backend) to draw a labelled box around them.

How do I show an actor as a person?

Declare it with actor instead of participant, for example actor U as User.