PlantUML Sequence Diagram Syntax With Mermaid Equivalents
November 11, 2026 · 11 min read
PlantUML Sequence Diagram Syntax, With Mermaid Equivalents
A plantuml sequence diagram is plain text between @startuml and @enduml that PlantUML draws as lifelines and arrows. Below are the constructs you'll actually use, each written correctly and translated to Mermaid, because GitHub renders Mermaid fences in Markdown but shows PlantUML as a plain code block.
PlantUML Sequence Diagram Basics: Participants and Messages
Every diagram starts with @startuml and ends with @enduml. A participant appears the first time you name it, but declaring it up front fixes the left-to-right order and lets you pick a shape. PlantUML offers participant, actor, boundary, control, entity, database, collections and queue.
@startuml
actor User
participant "Web App" as Web
database Postgres
User -> Web : Load orders
Web -> Postgres : SELECT orders
Postgres --> Web : 12 rows
Web -> Web : Format table
Web --> User : Orders page
@enduml
This draws a stick figure for User, a box labelled Web App and a cylinder for Postgres. Calls use -> (a solid line), replies use --> (a dotted line), and Web -> Web loops back onto its own lifeline. Quotes let a name contain spaces, and as gives it a short alias to type in messages.
Here's the same flow in Mermaid:
```mermaid
sequenceDiagram
actor User
participant Web as Web App
participant Postgres@{ "type": "database" }
User->>Web: Load orders
Web->>Postgres: SELECT orders
Postgres-->>Web: 12 rows
Web->>Web: Format table
Web-->>User: Orders page
```
Mermaid opens with sequenceDiagram, needs no end marker and takes labels after as without quotes. The @{ "type": "database" } shape syntax arrived in Mermaid 11.11.0, so an older renderer may reject that line. For flowcharts, Gantt charts and the other Mermaid diagram types, see our guide to Mermaid diagrams in Markdown.
Arrow Types in PlantUML and Their Mermaid Equivalents
Arrows are where most translations go wrong. The PlantUML sequence diagram reference builds arrows from small parts. A doubled dash makes the line dotted, a doubled head makes it thin, and a trailing x marks a lost message.
| PlantUML | What it draws | Mermaid |
|---|---|---|
A -> B | Solid line, filled arrowhead | A->>B |
A --> B | Dotted line, filled arrowhead | A-->>B |
A ->> B | Solid line, thin open arrowhead | A-)B (closest match) |
A ->x B | Lost message ending in a cross | A-xB |
A <-> B | Arrowheads at both ends | A<<->>B (Mermaid 11.0.0+) |
A ->o B | Circle at the arrowhead | No direct equivalent |
A -[#red]> B | Coloured arrow | No per-message colour |
The trap: in PlantUML, -> already has an arrowhead. In Mermaid, -> and --> draw a line with no head at all, according to the Mermaid sequence diagram docs. If you copy A -> B across literally, your diagram loses every arrowhead, so always translate to ->> and -->>.
Activation Bars, return and Lifelines in PlantUML
An activation bar shows when a participant is busy. You can write activate Auth and deactivate Auth on their own lines, but the shorthand after the target is faster:
@startuml
participant App
participant Auth
database DB
App -> Auth ++ : Validate token
Auth -> DB ++ : Look up session
DB --> Auth -- : Session row
return 200 OK
@enduml
++ activates the target, and -- deactivates the sender. The return keyword sends a reply to whoever caused the most recent activation still open, here App, and closes Auth's bar. Add autoactivate on at the top and every message activates its target, which pairs well with return.
Mermaid uses + and - straight after the arrow:
```mermaid
sequenceDiagram
App->>+Auth: Validate token
Auth->>+DB: Look up session
DB-->>-Auth: Session row
Auth-->>-App: 200 OK
```
Mermaid has no return and no autoactivate, so you write each reply yourself and remember the -. Every + needs a matching -, or the activation bar never closes.
PlantUML creates and destroys participants mid-flow with create Worker and destroy Worker, or with the ** and !! shortcuts after the target. In Mermaid, put create participant Worker before the first message to it and destroy Worker before the last message that involves it. That needs Mermaid 10.3.0 or later:
```mermaid
sequenceDiagram
participant App
create participant Worker
App->>Worker: Start export
destroy Worker
App-xWorker: Cancel
```
How Do You Show a Loop or Parallel Calls in PlantUML?
PlantUML groups messages with alt/else, opt, loop, par, break, critical and group. Each block closes with end, blocks nest, and the text after the keyword becomes the frame's label. Indentation is optional but makes nesting readable. Our UML sequence diagram guide explains what the first six of these fragments mean.
@startuml
Client -> API : POST /orders
alt stock available
API -> Stock : Reserve items
API --> Client : 201 Created
else out of stock
API --> Client : 409 Conflict
end
loop every 5 seconds
Client -> API : GET /orders/42
end
par
API -> Mail : Send receipt
else
API -> Ledger : Write entry
end
@enduml
The alt frame shows two branches split by a dashed line. The loop frame wraps the polling call, and the par frame shows two branches that run at the same time. In PlantUML, else adds a branch to whichever block is open, so it also separates par branches.
The Mermaid keywords mostly match, with two separators that differ:
```mermaid
sequenceDiagram
Client->>API: POST /orders
alt Stock available
API->>Stock: Reserve items
API-->>Client: 201 Created
else Out of stock
API-->>Client: 409 Conflict
end
loop Every 5 seconds
Client->>API: GET /orders/42
end
par Send receipt
API->>Mail: Send receipt
and Write ledger
API->>Ledger: Write entry
end
```
Mermaid's par uses and between branches, and critical uses option. Mermaid has opt, break and critical too, but no group. The closest substitute is rect rgb(230, 240, 255) ... end, which shades the messages without a label.
PlantUML also has an alternative layout engine called teoz. Add !pragma teoz true after @startuml, then start a message with & to draw it in parallel with the one above it. For example, & API -> Ledger : Write entry runs beside the receipt call. Mermaid has nothing like it, so the par block is your best translation.
Notes, Dividers, Delays and Autonumber
Long diagrams need signposts. PlantUML gives you numbering, notes, dividers, delays and spacers:
@startuml
autonumber 10 10
Client -> API : Upload file
note right of API : Virus scan runs here
== Processing ==
API -> Worker : Queue job
...2 minutes later...
Worker --> API : Job done
|||
note over Client, API
Client polls until
the job finishes
end note
hnote over Worker : idle
@enduml
autonumber 10 10 numbers messages 10, 20, 30. == Processing == draws a labelled divider across the diagram, ...2 minutes later... draws a dotted gap with text, and ||| adds blank space. A note can sit beside one participant, span two, or run over several lines until end note. hnote and rnote change its shape to a hexagon or a rectangle.
Mermaid covers less of this list:
```mermaid
sequenceDiagram
autonumber
Client->>API: Upload file
Note right of API: Virus scan runs here
API->>Worker: Queue job
Worker-->>API: Job done
Note over Client,API: Client polls until the job finishes
```
Mermaid has notes and autonumber, but no divider, delay, spacer, hnote, rnote or ref over. A wide Note over the first and last participants is the usual stand-in for a divider. Mermaid's autonumber also takes a start and a step, so autonumber 10 10 numbers messages 10, 20, 30 there too. A bare autonumber counts from 1.
Grouping Participants With box
A box draws a shaded frame behind related lifelines, such as everything inside one service:
@startuml
actor User
box "Backend" #LightBlue
participant API
database DB
end box
User -> API : Search
API -> DB : Query
@enduml
Mermaid closes the box with a plain end and puts the colour before the label:
```mermaid
sequenceDiagram
actor User
box LightBlue Backend
participant API
participant DB
end
User->>API: Search
API->>DB: Query
```
Use a colour name or rgb(), rgba(), hsl() values in Mermaid. Its docs say hex colours such as #ff0000 aren't supported in a box.
A Full PlantUML Sequence Diagram Example: Token Refresh
Here's a realistic flow that combines numbering, an alias, activation and an alt block. The app asks an auth server for a fresh access token, and the user only sees a sign-in page when the refresh fails.
@startuml
autonumber
actor User
participant App
participant "Auth Server" as Auth
User -> App : Open dashboard
App -> Auth ++ : Refresh token
alt token valid
Auth --> App : New access token
else token expired
Auth --> App -- : 401 Unauthorized
App --> User : Show sign-in page
end
@enduml
Translated to Mermaid, it renders live in the editor below. Change a message or add a branch and the diagram redraws as you type:
The - sits on one branch only. Mermaid reads the source top to bottom, so one + and one - balance even though only one branch runs in real life.
Does GitHub Render PlantUML Sequence Diagrams?
No. GitHub's diagram documentation lists four syntaxes for Markdown: Mermaid, GeoJSON, TopoJSON and ASCII STL. A fence tagged plantuml shows up as an ordinary fenced code block. To see which Mermaid version GitHub runs, put the single word info inside a mermaid fence.
GitLab is different. Its PlantUML integration docs say GitLab.com renders plantuml blocks with no setup. Self-managed GitLab needs an administrator to configure a PlantUML server first.
Everywhere else, you render PlantUML yourself and commit the image. The PlantUML jar needs Java, and java -jar plantuml.jar sequence.txt writes a PNG next to the file. You can also paste the source into the online server on plantuml.com, but that sends your diagram text to a third party.
You don't need Graphviz: PlantUML's docs list it only for diagrams such as class, use case and state diagrams. If you keep documentation in Markdown next to your code, that image is one more file to regenerate on every change.
Our editor behaves like GitHub here. It renders mermaid fences live in the preview, but it doesn't render PlantUML, so a plantuml fence stays a plain code block. Translate the diagram to Mermaid when you want to see it drawn.
PlantUML or Mermaid for Sequence Diagrams?
PlantUML has more sequence constructs: return, autoactivate, delays, spacers, ref over, teoz parallel messages, newpage and detailed skinparam styling. Mermaid wins on reach, because GitHub, GitLab and many Markdown editors draw it with zero setup. Confluence is one exception, and our guide to adding a Mermaid diagram in Confluence compares three ways around it.
We prefer Mermaid for diagrams that live in a README and PlantUML for large design documents that need return, ref or teoz. The honest limitation is that translation loses detail. A PlantUML diagram that leans on delays, dividers or coloured arrows comes out plainer in Mermaid, and no syntax trick brings those back.
If you're asking which tool is best overall, pick the one your docs platform renders without a plugin, which usually means Mermaid. For options beyond these two, our comparison of sequence diagram generator tools covers D2, ZenUML and draw.io.
A plantuml sequence diagram gives you more constructs than Mermaid, but Mermaid is the version GitHub and many Markdown previews actually draw. Keep the PlantUML source if your team needs return or teoz, and keep a Mermaid translation for READMEs. Paste the Mermaid version into the editor to check it renders, or open the Mermaid editor tool to preview it with a theme and export a PNG or SVG.