Learn

Sequence diagram syntax

Learn participants, actors, arrows, activation, notes, control blocks, and advanced Mermaid sequence features.

On this page16 sections

Syntax cheatsheet
1.Start a sequence diagram
2.Participants, actors, and aliases
3.Participant stereotypes
4.Solid arrows (requests)
5.Dashed arrows (responses)
6.Bidirectional arrows
7.Activation boxes
8.Create and destroy participants
9.Notes on the timeline
10.loop, alt, and opt blocks
11.par, critical, and break
12.Grouping boxes and background rects
13.Autonumber and actor links
14.Put it together: Auth sequence
Check your level

Syntax cheatsheet

Quick reference for this diagram type

Concept	Syntax
Declare	sequenceDiagram
Participant / actor	participant A as App · actor U as User
Stereotypes	participant DB@{ "type": "database" }
Solid / dashed	A->>B: msg · A-->>B: msg · A-xB · A-)B
Activation	A->>+B: call · B-->>-A: reply
Note	Note over A,B: text · Note right of A: text
Blocks	loop · alt · else · opt · par · critical · break · end
Create / destroy	create participant B · destroy B
Box / autonumber	box Aqua Group · autonumber
Actor links	link A: Label @ https://…

Start a sequence diagram

Begin with sequenceDiagram. Time flows top to bottom; participants are vertical lifelines.

Declare participants up front when you want a stable left-to-right order. Otherwise Mermaid creates them as messages appear.

sequenceDiagram
  participant User
  participant App
  User->>App: Open

Expand

Participants, actors, and aliases

participant draws a box lifeline; actor draws a stick figure — useful for humans vs systems.

Aliases keep message lines short: participant I as IdP shows “IdP” on the lifeline while you type I in messages.

Tip: Aliases are display-only — messages still use the short id.

sequenceDiagram
  actor U as User
  participant A as App
  participant I as IdP
  U->>A: Sign in

Expand

Participant stereotypes

Use JSON configuration on a participant to pick UML-style symbols: boundary, control, entity, database, collections, or queue.

You can combine stereotypes with an external as alias; the alias after as wins over an inline alias field.

Tip: Stereotype syntax is Preview/code oriented — Arrange preserves it when you switch modes.

sequenceDiagram
  actor U as User
  participant API@{ "type": "boundary" }
  participant Ctrl@{ "type": "control" }
  participant DB@{ "type": "database" }
  U->>API: Request
  API->>Ctrl: Handle
  Ctrl->>DB: Query

Expand

Solid arrows (requests)

A solid arrow (->>) is a synchronous or outbound call. Put the message text after the colon.

Use ->> for a filled arrowhead and -> for an open arrowhead when you want lighter visual weight.

sequenceDiagram
  participant U as User
  participant A as App
  participant I as IdP
  U->>A: Sign in
  A->>I: OAuth request

Expand

Dashed arrows (responses)

Dashed arrows (-->>) typically mark replies or async responses — tokens, redirects, or session cookies coming back.

Pair solid outbound with dashed return to make request/response pairs obvious. Cross (-x / --x) and async open (-) / --)) arrows are also supported.

sequenceDiagram
  participant U as User
  participant A as App
  participant I as IdP
  I-->>A: Token
  A-->>U: Session
  A-xU: Abort

Expand

Bidirectional arrows

Bidirectional arrows (<<->> / <<-->> , Mermaid v11+) show mutual exchange.

Central lifeline connections append () to the arrow so a message meets the midline — a Preview/code feature Arrange preserves as locked timeline rows.

sequenceDiagram
  participant A
  participant B
  A<<->>B: Sync handshake
  A<<-->>B: Async ack

Expand

Activation boxes

Activation shows when a participant is busy. Append + on a message to activate the target, and - to deactivate.

Nested activations stack, which helps when App talks to IdP while still handling the user request.

Tip: You can also write activate I / deactivate I on their own lines.

sequenceDiagram
  participant A as App
  participant I as IdP
  A->>+I: OAuth request
  I-->>-A: Token

Expand

Create and destroy participants

Prefix a message with create participant (or actor) to introduce a lifeline mid-flow. Use destroy before a message that ends a participant.

Only the recipient can be created; sender or recipient can be destroyed.

sequenceDiagram
  participant A as App
  create participant W as Worker
  A->>W: Start job
  destroy W
  A->>W: Finish

Expand

Notes on the timeline

Notes annotate why something happens without adding fake messages. Place them left of, right of, or over one or more participants.

sequenceDiagram
  participant U as User
  participant I as IdP
  Note right of I: Consent screen
  U->>I: Approve
  Note over U,I: User grants access

Expand

loop, alt, and opt blocks

Control blocks describe repeated or conditional behavior. loop wraps retries; alt / else branches; opt is an optional path.

Always close a block with end. Keep block bodies short so the diagram stays scannable.

sequenceDiagram
  participant A as App
  participant I as IdP
  alt Token valid
    A->>A: Continue
  else Token expired
    A->>I: Refresh
    I-->>A: New token
  end
  opt Show consent
    I-->>A: Consent required
  end

Expand

par, critical, and break

par / and shows concurrent work. critical / option models atomic work with contingency paths. break stops the sequence (often for exceptions).

sequenceDiagram
  participant A as App
  participant C as Cache
  participant D as DB
  par Fetch cache
    A->>C: GET
  and Fetch DB
    A->>D: SELECT
  end
  critical Commit
    A->>D: WRITE
  option Conflict
    A->>D: ROLLBACK
  end
  break Fatal error
    A-->>A: Abort
  end

Expand

Grouping boxes and background rects

box groups actors visually with an optional color and label. rect rgb(...)/rgba(...) highlights a span of messages with a background.

sequenceDiagram
  box rgb(33,66,99) Auth
    actor U as User
    participant A as App
  end
  participant I as IdP
  rect rgba(0, 255, 0, 0.1)
    U->>A: Sign in
    A->>I: OAuth request
  end

Expand

Autonumber and actor links

autonumber (optionally with start and increment) labels each message. link / links attach popup menu URLs to an actor for dashboards or docs.

sequenceDiagram
  autonumber
  actor U as User
  participant A as App
  U->>A: Sign in
  A-->>U: Session
  link A: Health @ https://example.com/health
  links A: {"Repo": "https://example.com/repo"}

Expand

Put it together: Auth sequence

Combine actor, activation, notes, and alt into the login handshake from the examples template — still Arrange-friendly.

sequenceDiagram
  actor U as User
  participant A as App
  participant I as IdP
  U->>+A: Sign in
  A->>+I: OAuth request
  Note right of I: Consent screen
  I-->>U: Consent
  U->>I: Approve
  I-->>-A: Token
  alt Session ok
    A-->>U: Session
  else Denied
    A-->>U: Error
  end
  deactivate A
  opt Remember device
    A->>A: Store cookie
  end

Expand

Check your level

80% or higher certifies this lesson. You'll get 3–5 random questions from a larger bank.

Back to examples