Skip to main content

Mermaid 11.15.0

Mermaid swimlane diagram cheat sheet

Mermaid has no native swimlane diagram. Use one flowchart subgraph per role to approximate lanes; choose a sequence diagram for message handoffs or architecture-beta for infrastructure groups.

Build this in Mermaid Flowchart Editor →

Quick start

Make each role a named subgraph, then connect actions across roles using their node ids.

Mermaid
Open in editor → 
flowchart LR
  subgraph author ["Author"]
    direction TB
    A["Draft"] --> B["Revise"]
  end
  subgraph reviewer ["Reviewer"]
    direction TB
    C["Check"] --> D["Approve"]
  end
  A --> C
  C --> B
  B --> D

Loading…

Syntax reference

Syntax reference
SyntaxMeaning
flowchart LR / flowchart TBUse flowchart syntax; swimlane is not a supported diagram keyword.
subgraph laneId ["Role"] / endGroup the actions belonging to one role. Lane ids and node ids must be distinct.
direction TB / direction LRRequest a local direction. External edges can override it.
A --> B / A -->|Handoff| BConnect actions across lanes by node id, optionally labeling the handoff.
laneA --> laneB / A ~~~ BSubgraph edges and invisible links can influence ordering without fixing coordinates.
style laneId fill:#f5f5f5,stroke:#a1a1a1Style the lane’s subgraph background and border directly.
classDef / class A name / A:::nameDefine reusable styles for action nodes inside the lanes.
%% / accTitle: / accDescr:Comments and accessible descriptions; all other flowchart syntax remains available.

One subgraph per responsibility

Keep ownership explicit: every action belongs to one role. Use lane ids for structural grouping and node ids for actions. Linking whole subgraphs is useful for coarse handoffs while preserving local layout direction.

Mermaid
Open in editor → 
flowchart LR
  subgraph writer ["Writer"]
    direction TB
    A["Outline"] --> B["Draft"]
  end
  subgraph editor ["Editor"]
    direction TB
    C["Review"] --> D["Sign off"]
  end
  writer --> editor

Loading…

Cross-lane edges and local direction

Draw a handoff between the actual action nodes when precision matters. That edge can cause the subgraph to inherit the global direction. An internal direction is a request, not a guaranteed swimlane orientation.

Mermaid
Open in editor → 
flowchart TB
  subgraph requester ["Requester"]
    direction LR
    A["Submit"] --> B["Respond"]
  end
  subgraph approver ["Approver"]
    direction LR
    C["Assess"] --> D["Approve"]
  end
  A -->|Request| C
  C -->|Changes| B
  B --> D

Loading…

Lane backgrounds and reusable action styles

Use direct style on subgraph ids for lane backgrounds. ClassDef styles the action nodes inside those groups. Keep borders visible and text readable; color complements role labels rather than replacing them.

Mermaid
Open in editor → 
flowchart LR
  subgraph drafting ["Drafting"]
    A["Write"]:::action
  end
  subgraph checking ["Checking"]
    B["Review"]:::action
  end
  A --> B
  style drafting fill:#f5f5f5,stroke:#a1a1a1
  style checking fill:#d3e5ff,stroke:#0070f3
  classDef action fill:#ffffff,stroke:#171717,color:#171717

Loading…

Spacing without fixed lanes

Increase rankSpacing to separate handoffs and nodeSpacing to separate actions. Mermaid still controls lane order, widths and node positions. For long processes, split the workflow into several diagrams.

Mermaid
Open in editor → 
---
config:
  flowchart:
    nodeSpacing: 40
    rankSpacing: 70
---
flowchart LR
  subgraph drafting ["Drafting"]
    A["Write"]
  end
  subgraph review ["Review"]
    B["Check"]
  end
  A --> B

Loading…

Common mistakes

Starting with a swimlane keyword

Mermaid does not recognize swimlane. Start with flowchart and create subgraphs.

Invalid syntax — corrected example below

swimlane
  Author --> Reviewer
Mermaid
Open in editor → 
flowchart LR
  subgraph author ["Author"]
    A["Draft"]
  end
  subgraph reviewer ["Reviewer"]
    B["Check"]
  end
  A --> B

Loading…

Assuming equal lane widths

Subgraphs size themselves around their contents. Invisible edges can help ordering, but cannot enforce a true fixed grid.

Limitations

  • Lane order and width are only indirectly controlled; the layout can reorder nodes.
  • Cross-lane node connections may override local direction.
  • Long processes with many handoffs quickly become cluttered.
  • Use architecture-beta for infrastructure groupings or a sequence diagram for ordered message exchanges; neither is a native swimlane replacement.

Frequently Asked Questions

Does Mermaid support native swimlanes?
No. This reference uses flowchart subgraphs as a practical approximation of lanes.
Can I force every lane to the same width?
There is no native equal-width lane setting. Layout and subgraph contents determine their dimensions.
When is a sequence diagram clearer?
Use a sequence diagram when the central story is which participant sends each message and in what order.