Swimlanes Diagram (v11.16.0+)

WARNING

This is a new diagram type in Mermaid. Its syntax may evolve in future versions.

A swimlane diagram shows a process divided by responsibility. Each lane represents an actor, team, system, or phase, and the nodes inside the lane show the work that happens there. Arrows show the order of work and the handoffs between lanes.

Use swimlane diagrams when the most important question is not only "what happens next?" but also "who owns this step?" They are useful for approval flows, support processes, delivery workflows, and any process where work crosses teams or systems.

Basic Example

The rendered examples on this page use the Neo look and the Redux theme. Out of the box, swimlanes use your configured default look and theme.

Code:

Ctrl + Enter|

Syntax

A swimlane diagram starts with the swimlane-beta keyword. You can optionally add a direction after the keyword.

swimlane-beta

swimlane-beta LR

The supported directions are:

Direction	Meaning
TB	Top to bottom
TD	Top down, same as TB
BT	Bottom to top
LR	Left to right
RL	Right to left

If no direction is set, the diagram uses TB.

Lanes

Use subgraph to create a lane. In a swimlane diagram, top-level subgraphs are rendered as swimlanes. A lane ends with end.

Code:

Ctrl + Enter|

You can give a lane an internal id and a display label. This is useful when the label contains spaces or when you want a stable id for styling.

Code:

Ctrl + Enter|

Nodes

Nodes use flowchart-style shape syntax. The id is written first, and the label is written inside the shape.

Code:

Ctrl + Enter|

The most common node forms are:

Syntax	Shape	Common use
id[Text]	Rectangle	Task or activity
id(Text)	Rounded rectangle	Step or event
id([Text])	Stadium	Start or end
id{Text}	Decision	Branching question
id((Text))	Circle	Connector or marker

For the complete shape catalog, icons, images, markdown strings, classes, and styling options, see Flowchart syntax.

Edges

Edges also use flowchart-style syntax. They can connect nodes in the same lane or across lanes.

Code:

Ctrl + Enter|

Common edge forms:

Syntax	Meaning
A --> B	Arrow
A --- B	Line without arrowhead
A -->|Label| B	Arrow with label
A -.-> B	Dotted arrow
A ==> B	Thick arrow

For the full edge syntax, including multi-directional arrows and minimum link length, see Flowchart syntax.

Accessibility

Use accTitle and accDescr to provide an accessible title and description.

Code:

Ctrl + Enter|

Good Practices

Make Each Lane Mean One Kind of Ownership

Choose lanes that answer "who owns this step?" Avoid mixing teams, phases, and statuses in the same diagram unless that distinction is the point of the diagram.

Code:

Ctrl + Enter|

Label Cross-Lane Handoffs

A cross-lane arrow is where responsibility changes. Label the arrow when the handoff depends on a document, decision, message, or condition.

Code:

Ctrl + Enter|

Keep Long Processes Readable

Split a large process into several diagrams when the lanes or handoffs stop fitting in one view. A useful swimlane diagram is usually readable without tracing every arrow twice.

Code:

Ctrl + Enter|

Use Stable Ids

Use short, meaningful ids for nodes and lanes. The label can change without breaking links, styles, or later references.

Code:

Ctrl + Enter|

Put Decisions Where They Are Made

Place a decision node in the lane that owns the decision. Then route the outcomes to the lanes that act on the result.

Code:

Ctrl + Enter|

When to Use Another Diagram

Use a regular flowchart when ownership is not important and you only need to show sequence or branching. Use a sequence diagram when the focus is messages over time between participants. Use a state diagram when the focus is how one thing changes state.