Beauty Diagram
Diagram type

Mermaid Sankey Diagram Syntax & Examples

Reference for Mermaid sankey diagram syntax — sankey-beta keyword, CSV-style source-target-value rows, and flow magnitude encoding. Copy-paste funnel & resource examples.

Use this page to connect a high-intent search query to the right problem-solution narrative.

At a glance

A syntax reference for Mermaid's `sankey-beta` grammar — read this when you need the exact way to express flow magnitudes between source and destination nodes, then try the result in the editor.

What is a sankey diagramBasic syntax — sankey-beta + CSV rowsMulti-stage flows — chaining rowsMagnitudes & visual encodingNode labels & special charactersCommon patterns & gotchas
Rendered proof
Sankey diagram of a simple traffic funnel.
Theme · Obsidian
Open this diagram in editor
This example could not be rendered in the proof block. The source is still available below.
View Mermaid sourcePlain-text diagram syntax — copy or edit directly.
diagram.mmd
1sankey-beta
2Visitors,Homepage,600
3Visitors,Blog,300
4Visitors,Pricing,100
5Homepage,Signup,150
6Blog,Signup,60
7Pricing,Signup,40
8Signup,Paid,70

What is a sankey diagram

A sankey diagram shows how a quantity flows from sources to destinations through intermediate stages, with the width of each ribbon proportional to the magnitude of that flow. The reader sees both the structure (which sources connect to which destinations) and the volume (how much) in one view. It is the right shape for any quantity-splitting question: marketing funnel conversion (visitors → signups → paid), energy or material flow (input → process → output), budget allocation (revenue → departments → categories), traffic analysis (channels → pages → conversions). If your data is purely categorical with no magnitude dimension, use a flowchart instead.

Basic syntax — sankey-beta + CSV rows

Every Mermaid sankey diagram starts with the `sankey-beta` keyword on its own line. (The `-beta` suffix reflects the diagram type's experimental status in Mermaid releases, but the grammar has been stable for over a year.) Each subsequent line is a CSV-style row with exactly three fields: `Source,Target,Value`. The source is the upstream node, the target is the downstream node, and the value is the numeric magnitude of the flow. Mermaid auto-creates nodes from these rows — declaring nodes separately is not needed and not supported.

  • `sankey-beta` — diagram type keyword (always first)
  • `Source,Target,Value` — CSV row format (one per line, no header)
  • Nodes are auto-created from rows — no separate node declaration

Multi-stage flows — chaining rows

A node can appear as both a target and a source in different rows — that's how multi-stage flows are built. For example, in a funnel: `Visitors,Homepage,600` says 600 visitors went to the homepage, and then `Homepage,Signup,150` says 150 of those continued to signup. The Homepage node serves as a destination for the first row and a source for the second. The renderer automatically positions intermediate nodes between stages, and the ribbon widths flow proportionally through them. Up to three or four stages reads cleanly; beyond that, ribbons cross over and individual flows become hard to track.

Magnitudes & visual encoding

The third field on each row is the flow magnitude — typically a count, a percentage, or a normalised value. Mermaid scales the entire diagram so the largest flow fits, and every smaller flow renders proportionally. This means absolute values don't matter — only ratios do. A funnel with values `1000 / 500 / 100` renders identically to one with `10 / 5 / 1`. Use the values that make sense for your data; the diagram will scale. The most common gotcha here: mixing scales accidentally — putting one flow in percent and another in count produces an unreadable diagram because the relative magnitudes are meaningless.

Node labels & special characters

Node labels can contain spaces, punctuation, and most special characters. If a label contains a comma (which is the field separator), wrap the entire label in double quotes: `"Signup, free plan",Paid,40`. Quoted labels can include commas, escaped quotes (`"He said \"hi\""`), and other punctuation that would otherwise confuse the parser. Avoid extremely long labels — they don't wrap, so a long label can push the diagram wider than expected. Two-to-four-word labels read cleanly.

  • Plain labels: `Homepage,Signup,150`
  • Labels with commas: `"Signup, free plan",Paid,40` (wrap in double quotes)
  • Labels with quotes: `"He said \"hi\"",...`

Common patterns & gotchas

Three patterns dominate real sankey diagrams. Conversion funnels are the most common — visitors split across landing pages, then narrow toward signup, then narrow further to paid (each stage smaller than the last). Resource flows are similar in shape but split-and-merge multiple times (raw input → processes → multiple outputs). Budget allocation is one-to-many (revenue → departments → categories). The most common gotcha: forgetting that nodes are auto-created from rows — typos in node names create separate nodes that don't connect to the rest of the flow (you end up with `Singup` and `Signup` as two different unconnected nodes). Always check the rendered output for unconnected fragments after editing.

  • Typos in node names silently create unconnected nodes — `Singup` vs `Signup`
  • Diagrams beyond 3-4 stages get noisy; consider splitting into multiple sankeys
  • Magnitudes are relative — mixing percentages with counts produces meaningless ratios
FAQ

Mermaid Sankey Diagram Syntax & Examples — frequently asked questions

What does a Mermaid sankey diagram show?

A sankey diagram visualises how a quantity flows from sources to destinations through intermediate stages, with the width of each ribbon proportional to the magnitude of that flow. It is the right pick for conversion funnels (visitors → signups → paid), resource flow analysis (input → processes → outputs), budget allocation (revenue → departments), and traffic source attribution. The reader sees both the structure and the relative volumes in one view, which is what makes sankey diagrams uniquely useful for quantity-splitting questions.

What's the syntax for a Mermaid sankey diagram?

Start with `sankey-beta` on its own line, then list flows as CSV rows in the form `Source,Target,Value`. Nodes are auto-created from these rows — declaring them separately is not supported. A typical funnel looks like: `Visitors,Homepage,600` followed by `Homepage,Signup,150` followed by `Signup,Paid,70`. The same node can appear as both a target and a source in different rows, which is how multi-stage flows are built. No header row, no curly braces, no semicolons.

How do I handle node labels that contain commas?

Wrap the label in double quotes: `"Signup, free plan",Paid,40`. Without the quotes, the comma inside the label would be interpreted as a field separator and the row would parse incorrectly. Quoted labels can also include escaped quotes (`"He said \"hi\""`) and other punctuation. Plain labels without commas don't need quoting. Avoid extremely long labels — they don't wrap, so a long label can push the diagram wider than expected.

How deep can a sankey diagram be?

Two or three stages reads cleanly. Four stages is the practical limit — beyond that, ribbons cross over and individual flows become hard to track visually. If the data has more stages than that, split into multiple sankey diagrams (one per phase of the funnel) or consider whether sankey is really the right shape — a flowchart with annotations might communicate the same content more clearly.

Why are some nodes in my sankey diagram disconnected?

Almost always a typo. Nodes are auto-created from the CSV rows, so if you reference `Singup` in one row and `Signup` in another, Mermaid creates two separate unconnected nodes. The renderer doesn't warn — it just shows both. Check every node name appearing in your source for consistent spelling, especially after editing or copy-pasting from a spreadsheet. Tools that auto-generate the CSV from data should normalise node names.