Beauty Diagram
Diagram type

PlantUML Swimlane Syntax & Examples

Reference for PlantUML swimlane syntax — `|lane|` declarations, coloured lanes (`|#Color|Name|`), cross-lane activity flow, and lane re-entry. Copy-paste examples.

Syntax reference, layout guidance, and ready-to-open examples for this diagram type.

At a glance

A syntax reference for PlantUML's swimlane lane syntax inside activity-beta diagrams — read this when you need to know how to declare a lane, tint it, or re-enter it later, then try the result in the editor.

What a swimlane diagram is forBasic lane declaration — `|Lane Name|`Coloured lanes — `|#Color|Name|`Re-entering a lane later in the flowHow Beauty Diagram renders PlantUML swimlanes differentlyCommon patterns & gotchas
Rendered proof
Order fulfilment across Customer, Order System, Warehouse, and Logistics lanes.
Theme · Atlas
Open this diagram in editor
Customer Order System Warehouse Logistics Start Place order & pay Reserve stock &create order Pick & pack Pick up & deliver Sign for delivery Close order &request rating Stop
View PlantUML sourcePlain-text diagram syntax — copy or edit directly.
diagram.puml
1@startuml
2|#FFE4B5|Customer|
3start
4:Place order & pay;
5|#B0E0E6|Order System|
6:Reserve stock & create order;
7|#FFB6C1|Warehouse|
8:Pick & pack;
9|#90EE90|Logistics|
10:Pick up & deliver;
11|Customer|
12:Sign for delivery;
13|Order System|
14:Close order & request rating;
15stop
16@enduml

What a swimlane diagram is for

Swimlanes split a process into vertical columns — one per team, role, or system — so every step is anchored to its owner. The visual answer to who-does-what is built into the layout itself, which is why PMs, business analysts, and SREs reach for swimlanes whenever a flow involves cross-team handoffs. The PlantUML implementation lives inside activity-beta syntax — every swimlane diagram is technically an activity diagram with lane declarations layered on top of the normal `start` / `:action;` / `stop` flow.

  • PRD user flows — Customer / Frontend / Backend / Third-party
  • Approval chains — Requester / Manager / Finance
  • Order fulfilment — Customer / Order System / Warehouse / Logistics
  • Incident runbooks — Monitoring / On-call / SRE Lead / Customer Support

Basic lane declaration — `|Lane Name|`

A lane is declared by wrapping a name in pipe characters on its own line: `|Customer|`. Subsequent actions belong to that lane until another `|Other Lane|` switches context. The first `|lane|` declaration creates the leftmost column; each new lane name introduces another column to the right. Lane order is fixed at declaration time — re-arranging activity lines inside the source does not re-order lanes. To control left-to-right ordering, control the order in which lanes first appear in the source.

  • `|Customer|` — plain lane declaration (renders as a labelled column)
  • First-appearance order = left-to-right column order
  • Lane names can contain spaces and most punctuation

Coloured lanes — `|#Color|Name|`

Lanes accept an optional colour prefix: `|#FFB6C1|Monitoring|` tints the lane with pink. The colour can be a hex value (`#FFB6C1`) or one of PlantUML's named colours (`#LightPink`, `#LightBlue`, `#PaleGreen`, `#MistyRose`, etc.). Coloured lanes are useful for signalling category — light pink for monitoring/alert lanes, light blue for infrastructure lanes, light green for resolution lanes is a common convention. Beauty Diagram preserves your colour hint but maps it toward the active theme's tonal range, so the same source renders consistently against light or dark canvases without changing the source.

Re-entering a lane later in the flow

A lane can be re-entered by writing `|Lane Name|` again later in the source — the colour does not need to be repeated (and would be ignored if you did). This is the standard pattern for processes that hand off, do work in another lane, then return: `|Employee|` declares first, work in other lanes happens, then `|Employee|` later switches back. Re-entry produces a horizontal handoff edge in the rendered output. The lane keeps its colour from the original declaration — only the active lane changes.

  • `|Lane|` re-used later switches context; colour does not need to be repeated
  • Handoff edges between lanes render as orthogonal L-shapes in Beauty Diagram
  • Use re-entry to model approve-and-return or escalate-and-resolve patterns

How Beauty Diagram renders PlantUML swimlanes differently

PlantUML's reference renderer stacks lanes vertically as subgraphs by default. Beauty Diagram detects the swimlane pattern (≥ 2 lane declarations + ≥ 1 cross-lane edge) and renders the lanes as side-by-side horizontal columns instead — which is the convention most modern PRDs and runbooks expect. Activities snap to the centre of their lane, adjacent lanes touch with shared inner borders, and cross-lane handoffs route as L-shapes rather than bezier S-curves. The source is unchanged; only the rendering convention differs.

Common patterns & gotchas

Three patterns dominate real swimlane diagrams. Linear handoffs (lane → lane → lane with no branches) are the simplest and most common. Approval chains pair lanes with `if-else` decisions — the approver lane has the diamond, downstream lanes pick up each outcome. Escalation patterns use lane re-entry — the on-call lane hands off to SRE Lead, then returns to on-call to apply the fix. The most common gotcha: declaring only one lane produces no horizontal layout — at least two lanes must exist before Beauty Diagram switches from the default vertical stack to side-by-side columns. Second gotcha: forgetting that lanes are activity-beta only — they don't work in legacy activity syntax or in sequence diagrams.

  • Only one lane = no swimlane layout (need ≥ 2 lanes and ≥ 1 cross-lane edge)
  • Lanes only exist inside activity-beta syntax — not in sequence or other PlantUML diagrams
  • Lane colour is set at first declaration; re-entry inherits the original colour
FAQ

PlantUML Swimlane Syntax & Examples — frequently asked questions

How do I declare a lane in PlantUML swimlane syntax?

Wrap the lane name in pipe characters on its own line: `|Customer|`. Every subsequent action belongs to that lane until another `|Other Lane|` switches context. The first lane declaration creates the leftmost column; each new lane name introduces another column to the right. Lane order is fixed at first declaration — to change the visual order, change which lane appears first in the source.

How do I add colour to a PlantUML swimlane?

Prefix the lane declaration with a colour: `|#FFB6C1|Monitoring|` tints the lane with pink. Both hex values (`#FFB6C1`) and PlantUML's named colours (`#LightBlue`, `#Pink`, `#FFE4B5`...) work. Colour is only specified on the first declaration of a lane — re-entering the same lane later (just `|Monitoring|`) inherits the original colour and doesn't need it repeated. Beauty Diagram maps your colour hint toward the active theme's tonal range so the result reads against any canvas.

Can I switch back to an earlier lane?

Yes. Re-write the lane name on its own line: `|Customer|` (no colour needed). This is the standard pattern for hand-offs that come back — the customer initiates, processing happens in other lanes, then the customer signs for delivery and we re-enter `|Customer|`. Re-entry renders as a horizontal handoff edge connecting the previous activity back to the lane. Approval chains and escalate-then-resolve runbooks use this pattern constantly.

Does PlantUML support horizontal swimlanes by default?

PlantUML's reference renderer stacks lanes vertically — every lane becomes a vertical strip on the canvas, even if the flow moves between lanes. Beauty Diagram instead renders lanes as side-by-side horizontal columns once at least two lanes and one cross-lane edge exist, which is the convention modern PRDs and runbooks expect. The source is unchanged; only the rendering differs. To get back to PlantUML's vertical stack convention, paste the source into the official PlantUML web editor instead.

Why does my swimlane diagram render as a vertical stack?

Two common reasons. First, you only have one lane — Beauty Diagram only switches to horizontal columns when at least two `|lane|` declarations exist. Second, you have multiple lanes but no edge crosses between them — Beauty Diagram looks for at least one cross-lane transition to confirm the diagram is meant to be a swimlane rather than a parallel set of unrelated flows. Add a second lane plus an action that moves between lanes, and the layout flips to side-by-side columns.