Mermaid vs PlantUML Swimlane Diagrams: Roles and Examples

This article focuses only on swimlane diagram expression. It does not cover Markdown support, documentation platform integration, plugins, or rendering services. For those broader tool differences, see the series overview: Mermaid vs PlantUML: Which diagram-as-code tool should you choose in 2026?.

The short version: with the Mermaid 11.6.0 version currently used by OnUML, Mermaid can approximate swimlane diagrams with Flowchart subgraph, which works well for lightweight role grouping. PlantUML has native Activity Diagram swimlane syntax, which is a better fit when responsibility boundaries and cross-role flow matter.

One version detail matters here. Mermaid added swimlane-beta in 11.16.0+, but that is a newer beta feature. OnUML currently uses Mermaid 11.6.0, which does not support swimlane-beta. For that reason, the Mermaid examples in this article use the Flowchart subgraph approach that works in the current project.

The key question in a swimlane diagram is not just "can the process be drawn?" It is "who owns each step?" If you only need visual grouping by role, department, system, or service, Mermaid subgraph works well. If each action needs to clearly belong to the current lane and the flow needs to move naturally across lanes, PlantUML's |Lane| syntax is closer to a real swimlane diagram.

More precisely:

Mermaid is simple for grouping. Put nodes inside subgraph Customer, subgraph Support, or subgraph Warehouse, then connect them with normal arrows. The syntax is short and readable, which makes it a good fit for product docs and lightweight process notes.

PlantUML has clearer swimlane semantics. You can switch lanes with |Customer|, |Support|, or |Warehouse|, and subsequent actions naturally belong to the current lane. Swimlanes also combine well with if, repeat, while, and fork.

This comparison is based on official documentation and the current OnUML dependency version:

• Mermaid Flowchart documentation
• Mermaid Swimlanes documentation
• PlantUML Activity Diagram Swimlanes documentation

Key Differences

In one sentence:

Mermaid swimlanes are more like grouped flowcharts; PlantUML swimlanes are more like responsibility-aware activity diagrams.

Mermaid Can Approximate Lightweight Swimlanes

Here is a return workflow: a customer submits a request, support reviews it, the warehouse receives and inspects the item, and finance issues the refund.

Mermaid

flowchart LR
  subgraph Customer
    C1[Submit return request]
    C2[Ship item back]
    C3[Receive refund]
  end

  subgraph Support
    S1[Review request]
    S2[Send return label]
    S3[Notify result]
  end

  subgraph Warehouse
    W1[Receive item]
    W2[Inspect item]
  end

  subgraph Finance
    F1[Issue refund]
  end

  C1 --> S1
  S1 --> S2
  S2 --> C2
  C2 --> W1
  W1 --> W2
  W2 --> S3
  S3 --> F1
  F1 --> C3

PlantUML

@startuml
|Customer|
start
:Submit return request;

|Support|
:Review request;
:Send return label;

|Customer|
:Ship item back;

|Warehouse|
:Receive item;
:Inspect item;

|Support|
:Notify result;

|Finance|
:Issue refund;

|Customer|
:Receive refund;
stop
@enduml

For a simple "role grouping plus sequential flow" diagram, both tools communicate the idea. Mermaid's subgraph is visual grouping; PlantUML's lane switching is responsibility semantics.

PlantUML Is Better for Complex Cross-Lane Flows

When a swimlane diagram includes branches, rejection paths, repeated revisions, or parallel work across roles, PlantUML's advantages become clearer.

Mermaid

flowchart LR
  subgraph Requester
    R1[Create purchase request]
    R2[Revise request]
    R3[Receive goods]
  end

  subgraph Manager
    M1[Review request]
    M2{Approved?}
  end

  subgraph Procurement
    P1[Create purchase order]
    P2[Confirm supplier]
  end

  subgraph Warehouse
    W1[Prepare receiving plan]
  end

  subgraph Finance
    F1[Reserve budget]
  end

  R1 --> M1 --> M2
  M2 -- No --> R2 --> M1
  M2 -- Yes --> P1 --> P2
  P2 --> W1
  P2 --> F1
  W1 --> R3
  F1 --> R3

PlantUML

@startuml
|Requester|
start
:Create purchase request;

|Manager|
:Review request;

if (Approved?) then (yes)
  |Procurement|
  :Create purchase order;
  :Confirm supplier;

  fork
    |Warehouse|
    :Prepare receiving plan;
  fork again
    |Finance|
    :Reserve budget;
  end fork

  |Requester|
  :Receive goods;
  stop
else (no)
  |Requester|
  :Revise request;
  |Manager|
  :Review request again;
  stop
endif
@enduml

Mermaid can approximate this with subgraphs, diamond nodes, and multiple edges, but complexity moves into edge management:

• Mermaid lanes are grouping containers; PlantUML lanes carry activity ownership.
• Mermaid parallel work is usually one-to-many edges; PlantUML has fork.
• Mermaid revision loops are back edges; PlantUML can write them as workflow control.
• PlantUML lane switching keeps the code close to the actual process narrative.

When to Choose Which

Choose Mermaid for swimlane-style diagrams when:

• You need to group a process by a few roles.
• The diagram belongs in README, product docs, or lightweight design notes.
• The workflow is mostly sequential steps and a few decisions.
• You do not need strict fork/join, loops, interrupts, or activity ownership semantics.
• Readers mainly need to know which role does which task.

Choose PlantUML when:

• You need formal activity-diagram swimlane semantics.
• Every action must clearly belong to a role, team, system, or service.
• The flow includes complex conditions, loops, parallel work, or early exits.
• The process switches between lanes frequently and needs readable source code.
• You need lane colors or consistent review output.

FAQ

Does Mermaid have native swimlane syntax?

Mermaid 11.16.0+ added swimlane-beta, but OnUML currently uses Mermaid 11.6.0, which does not support it. In the current project, use Flowchart subgraph to approximate swimlanes. It works well for lightweight grouping, but it is not the same stable activity swimlane semantics as PlantUML's |Lane|.

Can Mermaid connect across subgraphs?

Yes. Nodes in different subgraph blocks can be connected with normal edges. That is the common way to draw lightweight swimlane-style diagrams in Mermaid Flowchart.

Can PlantUML swimlanes be combined with branches, loops, and parallel flows?

Yes. PlantUML Activity Diagram swimlanes can be combined with if, repeat, while, fork, and other activity control structures.

How should I choose based only on diagram capability?

If you only need role-based grouping, Mermaid is enough. If you need formal swimlane semantics, complex control structures, and clear activity ownership, PlantUML is the better choice.

Bottom line:

For swimlane diagrams, Mermaid is good for lightweight responsibility grouping, while PlantUML is better for formal cross-role activity flows. Mermaid is fast; PlantUML has stronger semantics.

You can try the examples in the OnUML editor by switching between Mermaid and PlantUML modes.