Mermaid Sankey Diagram Tutorial: Flow and Volume Diagrams from CSV Data

A Sankey diagram is the picture you want whenever a quantity moves through a system and splits along the way - a budget flowing from revenue into departments, energy moving from sources to end uses, or users progressing through a funnel and dropping off at each stage. The defining feature is that the width of each flowing ribbon is proportional to its value, so the eye immediately sees where the big flows and the big losses are. Mermaid renders these from a strikingly compact input: essentially a small CSV of source, target, and value.

This guide covers Mermaid's "sankey-beta" syntax and the thinking that makes a Sankey clear rather than tangled, with examples ready for the Mermaid editor at /diagram-tools/mermaid-editor. The rendered diagram is editable in Atlas Diagram Studio at /diagrams, and because the input is so close to raw data, a Sankey is easy to regenerate as the numbers change. To go from a description of your flows to a starting diagram, the AI diagram generator at /diagram-tools/ai-diagram-generator can produce the initial rows for you to correct.

The CSV-style syntax

A Sankey diagram begins with the line "sankey-beta", and every line after it is a single flow written as three comma-separated fields: the source node, the target node, and the numeric value. A line like "Revenue,Engineering,40" means forty units flow from Revenue to Engineering. Mermaid discovers the nodes automatically from the names you use - you never declare them separately, so a node simply exists because it appears as a source or a target somewhere in your data.

Because nodes are inferred from the flows, chaining is natural: if Engineering then splits into Salaries and Tooling, you add lines with Engineering as the source, and Mermaid connects the whole chain. Node names that contain commas or special characters can be wrapped in double quotes, and a value can be a decimal. This closeness to a spreadsheet is deliberate - you can often paste columns from a data export and have a Sankey with minimal reshaping.

Building a clear flow

The syntax is trivial; the craft is in structuring the flows so the diagram reads clearly. The bullets below capture the habits that keep a Sankey legible as it grows.

• Start with the header line "sankey-beta", then one "source,target,value" row per flow.
• Let nodes be implicit - a node exists as soon as it appears as a source or target in any row.
• Chain stages by reusing a node as the source of the next set of flows, e.g. Revenue to Team, then Team to Cost.
• Quote names with special characters: '"Sales, EU",Marketing,20'.
• Keep values in consistent units, since ribbon width compares them directly.
• Order your rows by stage so the source is easy to follow from left to right.
• Watch that flows into and out of a node balance if your data is meant to conserve total volume.

Reading value and conservation

The persuasive power of a Sankey comes from proportional widths, so the values must be trustworthy for the picture to be honest. When a Sankey depicts something that should conserve - a budget where every dollar in must be allocated, or a funnel where users either advance or drop out - the total flowing into a node should equal the total flowing out, and any gap represents an unaccounted amount. Making that balance explicit, for example by adding an explicit "Unallocated" or "Churned" target, turns a vague picture into an accurate one.

Not every Sankey needs to conserve, though. Some show flows that legitimately grow or shrink, and forcing artificial balance would mislead. The judgment is to decide up front whether your quantity is conserved and then either enforce the balance or clearly signal that it is not. Either way, keeping the source data as the single source of truth - and regenerating the diagram from it - is what keeps the widths honest over time.

When a Sankey is the right choice

Reach for a Sankey when the story is about magnitude and distribution of a flow: how a budget is split, where energy or water goes, how traffic moves through a site, or where a hiring pipeline loses candidates. It is uniquely good at making losses and dominant paths obvious. It is the wrong choice when you care about the order of events over time - that is a timeline or sequence diagram - or about precise category comparison, which an xychart bar chart shows more legibly.

Because the input is essentially data, a Sankey slots neatly into reporting workflows where the numbers update regularly. Draft it in the Mermaid editor at /diagram-tools/mermaid-editor, refine and brand it in Atlas Diagram Studio at /diagrams, and export it for a report or dashboard. For the other data-shaped Mermaid diagrams - pie, xychart, quadrant - the complete Mermaid guide at /guides/mermaid-js-complete-guide covers when each fits, and the guide on turning text into diagrams at /guides/text-to-diagram-with-ai covers generating the first draft from a prompt.