Swimlane Diagram
Last updated:
Mermaid Studio provides language support for Swimlane diagrams inside IntelliJ IDEA and other JetBrains IDEs. A swimlane diagram is a flowchart whose nodes are grouped into lanes, so each step sits in the lane of the actor, team, or system responsible for it. Lanes make hand-offs between roles legible at a glance, which suits process maps and cross-functional workflows.
Swimlane requires Mermaid 11.16.0 or later, which Mermaid Studio bundles and uses as the default rendering version in this release.
Syntax Highlighting
Section titled “Syntax Highlighting”Syntax highlighting integrates directly with IntelliJ’s color scheme system, so diagram colors always match your editor theme. The screenshots below show the same swimlane source rendered across the Armada Dark, Islands Dark, and Islands Light themes.
IDE Support
Section titled “IDE Support”The summary below shows the IDE support Mermaid Studio ships for swimlane diagrams, grouped by capability.
Folding lets you collapse and expand structural blocks of the diagram source (subgraphs, frontmatter, multi-line strings) directly in the editor gutter. It keeps long diagrams navigable without forcing you to scroll past detail you don’t need right now.
Use the gutter triangles, Code → Folding, or the standard JetBrains shortcuts (
When the cursor sits next to a bracket, brace, or paren, Mermaid Studio highlights its matching pair across the whole diagram and lets you jump between them. This is especially valuable in nested syntax (subgraph blocks, JSON-style style strings, multi-shape labels) where it’s easy to lose track of which closer goes with which opener.
The line-comment action (
When you type a quote character to start a string, Mermaid Studio inserts the matching closing quote and places the cursor between them. Backspacing through an empty pair removes both characters at once. This keeps quoted labels balanced and reduces fiddly cursor work.
The formatter rewrites your diagram source to a canonical layout (consistent indentation, alignment of multi-line links, normalized whitespace around operators) without changing semantics.
It also clears up the whitespace mistakes that Mermaid’s parser is picky about, normalizing spacing between tokens so the parser accepts the diagram on the first read instead of throwing a confusing syntax error.
Run it with Code → Reformat Code (
Pressing
A dedicated Grammar-Kit parser backs the highlighting, so tokens are colored by what they mean in the diagram (a type reference versus a label versus a style), not just what they look like. The same parser validates the syntax as you type, flagging malformed statements in place instead of letting one mistake cascade through the file.
This is the foundation richer features build on; the same grammar drives completions, refactoring, and inspections.
Per-diagram annotators apply rule-based highlighting above the lexer and parser, running on every keystroke and painting their results directly in the editor. Mermaid Studio uses them across the full range the platform supports: highlighting that token types alone cannot decide (coloring a reference by what it resolves to), semantic errors and warnings (an edge pointing at an undefined node, an invalid direction value), and inline cues such as marking duplicate labels. Unlike inspections (configurable checks listed in Settings), annotators are always on, whether a rule ends in a color or a warning.
As you type, Mermaid Studio offers context-aware suggestions filtered to what’s valid at the cursor: node shapes, arrow types, keywords, icon names, identifiers, frontmatter keys, theme variables, and more. Completions cut down on typos and make the diagram syntax self-documenting.
Completion and validation for the YAML frontmatter block above the diagram body, driven by the diagram type’s slice of the Mermaid config schema. Config keys, enum values, and color properties complete as you type, and unknown or mistyped keys are flagged in place.
Hex, named, and rgb()/hsl() colors in style declarations get a small color swatch rendered in the gutter.
Click the swatch to open the IntelliJ color picker and pick a new value, and the source updates in place.
A dedicated page under Settings → Editor → Color Scheme for the diagram type, listing every highlighting attribute its parser produces with a live preview. This is what makes the difference between “the theme colors it somehow” and “you decide exactly how keywords, identifiers, labels, and styles render”.
Inspections are static analyzers that run continuously and surface problems as you edit: duplicate IDs, undefined references, malformed syntax, deprecated patterns, missing required fields. Each inspection has a configurable severity (error, warning, info), can be suppressed inline, and most ship with a quick fix that resolves the issue with one keystroke.
This is where most of the editorial intelligence lives: a diagram type with rich inspections is much harder to break in subtle ways.
Rename refactoring (
Find Usages (
Code Vision renders small inline indicators above declarations, typically reference counts (“5 references”, “3 inbound edges”), so you can see at a glance how connected an element is without running Find Usages. Click an indicator to jump to the references list.
Hovering an element with
The Structure tool window (
Double-click an element in the preview to edit its label in place. An editable overlay appears over the element, and committing the change writes it back to the source. Which elements are editable varies by diagram type.
A property inspector docked next to the preview that restyles the selected element (colors, presets, and diagram-type-specific controls) and writes the result back as Mermaid styling syntax.
Double-click an element to edit its label in place. The change is written back to the source when you commit it.
Drag an element to a new position, rewriting the source order or layout hints to match.
Insert new nodes or containers from the toolbar, or drag a connection handle to empty canvas to create a connected element.
Drag an edge endpoint onto a different element to rewire the connection in the source.
Wrap a selection in a new container with
Remove the selected elements and their source, including batch deletion of a multi-selection.
Built on the Flowchart Language
Section titled “Built on the Flowchart Language”A swimlane is a flowchart with lanes, so Mermaid Studio reuses its flowchart language tooling rather than reimplementing it.
The swimlane-beta language inherits the flowchart parser and lexer, which means the flowchart IDE intelligence in the summary above (completions, inspections, refactoring, formatting, and the rest) applies to swimlane source unchanged.
For the full reference on these capabilities, see the Flowchart diagram page.
Drag-to-Reorder Lanes in the Live Preview
Section titled “Drag-to-Reorder Lanes in the Live Preview”Each lane in a swimlane diagram is a subgraph block in the source, and the order of those blocks is the order of the lanes.
The live preview turns that mapping into a direct manipulation: in edit mode you can drag a lane to a new position and the plugin rewrites the subgraph order in the .mmd file to match.
This reuses the same visual-editing pipeline as flowchart node moves, so the source stays formatted and the change is undoable like any other edit.
The gesture follows the on-screen lane layout, which depends on the diagram direction.
In LR and RL diagrams the lanes are horizontal bands stacked top to bottom, so you drag a lane up or down past a neighboring lane’s edge.
In TB and BT diagrams the lanes are vertical columns set side by side, so you drag a lane left or right instead.
Either way an insertion line marks where the lane will land before you drop it, and the resulting subgraph order is the same regardless of direction.
The clip below shows a lane being dragged to a new position and the source updating in step.
Lane reordering is part of preview edit mode. For how edit mode works, how to enter it, and the other gestures it supports, see Visual Editing in the Live Preview.
Quick Syntax Reference
Section titled “Quick Syntax Reference”A swimlane diagram opens with the swimlane-beta keyword and a direction, then declares each lane as a subgraph and wires the nodes together with flowchart edges.
The example below routes a support request across three lanes:
swimlane-beta LR subgraph Customer request[Request service] receive[Receive update] end
subgraph Support triage[Triage request] answer[Send answer] end
subgraph Engineering investigate[Investigate issue] fix[Prepare fix] end
request --> triage triage -->|Known issue| answer triage -->|Needs code change| investigate investigate --> fix --> answer answer --> receiveKey elements:
- Start with
swimlane-betafollowed by a direction such asLR(left to right) orTB(top to bottom) - Declare each lane as a
subgraph Name ... endblock; the block order sets the lane order - Place a node inside the lane of the actor or system responsible for it
- Connect nodes with the usual flowchart edge syntax (
-->,-->|label|, chaineda --> b --> c)
Because swimlane shares the flowchart grammar, node shapes, edge styles, CSS classes, and linkStyle declarations all work the same way they do in a flowchart.
For complete syntax details, see the Mermaid Swimlane documentation.