When should I use `participant` vs `actor`?

Use `actor` for humans, end users, or external roles you want rendered as a stick figure — it signals a different category at a glance. Use `participant` for systems, services, databases, APIs, or anything that is not a human. Both produce a lifeline; the difference is purely visual but it helps readers identify the human entry points immediately, which is useful in any diagram involving end-user interaction.

How do I show a return message in Mermaid sequence diagrams?

Use the dashed arrow `-->>` — for example `Auth-->>App: 200 OK + token`. Solid `->>` arrows are reserved for requests and calls; dashed `-->>` are reserved for returns and responses. This solid/dashed distinction is the single most important visual signal in a sequence diagram, so keep it consistent — reusing solid for both directions makes the diagram much harder to read.

What's the easiest way to show a conditional path?

Use the `alt` block: `alt Success ... else Error ... end`. Both branches are visible at once with a labelled rectangle spanning the relevant lifelines, so the reader sees the fork without having to follow two diagrams. For an optional-but-not-conditional path (the action happens or it doesn't), use `opt Description ... end` instead — there's no else branch.

How do I show that two things happen at the same time?

Use the `par` block: `par Fetch profile ... and Fetch settings ... end`. Each parallel branch lives in its own labelled section but renders side by side on the same vertical axis, which is the visual cue that they run concurrently. This is the right tool for fan-out patterns (request several services in parallel) and for showing async background work that doesn't block the main thread.

Does Beauty Diagram preserve activation bars?

Yes. Activation bars (`activate Name` / `deactivate Name`, or the `->>+` / `-->>-` shorthand) survive beautification — they are essential semantics for showing when each participant is busy and the renderer never strips them. Activations are particularly valuable for nested call stacks where the outer service stays busy while an inner service is also busy; the overlapping bars make the call depth visible.

Diagram type

Mermaid Sequence Diagram Syntax & Examples

Reference for Mermaid sequence diagram syntax — actors vs participants, message arrows (->>, -->>, -x), activations, alt / opt / loop blocks, and notes. Copy-paste examples.

Use this page to connect a high-intent search query to the right problem-solution narrative.

At a glance

A syntax reference for Mermaid's `sequenceDiagram` grammar — read this when you need the exact way to write a return arrow, an alt block, an activation, or a note, then try the result in the editor.

What is a Mermaid sequence diagramActors vs participantsMessage arrows — solid, dashed, lost messagesActivations — show when an actor is busyAlt, opt, loop, par — control-flow blocksNotes & common patterns

Rendered proof

A sign-in exchange with three participants — exercises participant declaration, request/return arrows, and a typical authentication shape.

Theme · Modern

Open this diagram in editor

View Mermaid sourcePlain-text diagram syntax — copy or edit directly.

diagram.mmd

1sequenceDiagram
2  actor User
3  participant App
4  participant Auth
5  User->>App: Open /login
6  App->>Auth: POST /sessions
7  Auth-->>App: 200 OK + token
8  App-->>User: Redirect to /dashboard

Open in editor with this template

What is a Mermaid sequence diagram

A Mermaid sequence diagram describes a process as messages exchanged between actors over time. Each participant gets a vertical lifeline, and time flows top-to-bottom. It is the right shape for any process where the question is what-order-do-things-happen-in: API handshakes, authentication flows, service-to-service orchestration, incident timelines, request/response patterns with retries. If your diagram is more about decisions and branching than message order, use a flowchart instead; if it is about who-owns-what, use a swimlane. Sequence diagrams encode time directly into the layout, which makes them harder to misread than any flowchart attempting the same content.

Actors vs participants

The diagram starts with `sequenceDiagram` followed by a declaration of each participant. `participant Name` declares a generic participant rendered as a rectangle. `actor Name` renders as a stick figure — use this for humans or external roles. Order matters: the order participants are declared is the order their lifelines appear left-to-right. Declaring participants explicitly at the top is optional (Mermaid will auto-create them when first referenced), but explicit declaration gives you control over both order and label, which is usually what you want for a finished diagram.

`participant Name as "Display Label"` — separate id and visible label
`actor User` — human or external role rendered as a stick figure
Declaration order = left-to-right lifeline order

Message arrows — solid, dashed, lost messages

Messages connect lifelines. `A->>B: Label` is a solid filled arrow (the default for a request or call). `A-->>B: Label` is a dashed arrow with an open arrowhead (the default for a return). `A-)B: Label` is an async message (open triangle, dashed). `A--xB: Label` is a lost message. Solid vs dashed is the key reading signal: solid for cause, dashed for effect. Beauty Diagram preserves these conventions through beautification — the request/return distinction is the most important semantic in a sequence diagram and the renderer never collapses them into a generic line.

`->>` — solid arrow (request, call, command)
`-->>` — dashed arrow (return, response)
`-x` / `--x` — lost message (with x endpoint)
`-)` / `--)` — async message (open triangle)

Activations — show when an actor is busy

Activation bars are vertical rectangles overlaid on a lifeline that show when that participant is processing. Activate explicitly with `activate Name` (and `deactivate Name`), or use the shorthand `A->>+B: request` (activates B on receipt) and `B-->>-A: response` (deactivates B on return). Activations are particularly useful for showing nested call stacks — an outer service is still busy while an inner service is also busy — because the bars overlap visibly. Without activations, the reader has to mentally track call depth, which loses fidelity quickly past two levels.

Alt, opt, loop, par — control-flow blocks

Sequence diagrams support four control-flow blocks. `alt Description ... else Description ... end` is the two-or-more-way conditional (success vs error, or A vs B vs C). `opt Description ... end` is the conditional that only has the positive branch (the action happens or it doesn't). `loop Description ... end` is repetition (poll, retry, schedule). `par Description ... and Description ... end` is parallel execution (two things happen at the same time). All four blocks render as labelled rectangles spanning the relevant lifelines, with the description as the title. The reader can see at a glance which messages are conditional vs always-happens vs repeated.

`alt ... else ... end` — branching with multiple outcomes
`opt ... end` — single conditional branch
`loop ... end` — repetition with a labelled boundary
`par ... and ... end` — parallel execution

Notes & common patterns

Sequence diagrams support notes (`Note left of Name: Text`, `Note over A,B: Text`) for callouts that are not messages — preconditions, references to specs, edge cases worth flagging. Three patterns dominate real sequence diagrams: request/response (the most basic, two arrows with `-->>` return), error fork (an `alt` block where one side is success and the other is an error path with a different return), and retry loop (a `loop` block wrapping a request/response pair, often with an exit condition labelled in the loop description). The most common gotcha: forgetting that participants are declared in lifeline-order, so reordering messages does not reorder lifelines — to change the visual order, change the participant declarations at the top.