Sankey Diagrams: What They Show, When to Use Them, and How to Build One

Sankey diagrams visualize flows between nodes with width proportional to quantity. Perfect for showing user journeys, energy flows, budget allocation, and any process where items move between states.

What Does the Width of a Sankey Diagram Encode?

Width encodes magnitude: a link twice as wide carries twice the quantity, and a node's height equals the sum of everything flowing through it. That is the entire visual grammar — position and color are just organization. It also implies a conservation rule: flows into a node should equal flows out (plus any explicit "exit" or "loss" link), and if your numbers don't add up, the diagram will visibly lie.

Node "Product Page" (height = 700)
  in:  Homepage -> Product Page   (400)
       Paid ads -> Product Page   (300)
  out: Product Page -> Cart       (250)
       Product Page -> Exit       (450)

400 + 300 = 250 + 450  ✓ flows conserve

When Should You Use a Sankey Diagram (vs Alternatives)?

Use a Sankey when quantities move through 2–5 stages and the splits and merges are the story. If there is only one stage of splitting, a bar chart is easier to read; if every user moves strictly forward through fixed steps, a funnel chart is simpler; if you're showing part-to-whole at a single point in time, use a treemap or stacked bar instead.

Your data looks like	Better choice
Multi-stage flows that split and merge	Sankey diagram
Strictly linear drop-off (step 1 → 2 → 3)	Funnel chart
One categorical breakdown	Bar chart
Part-to-whole hierarchy at one moment	Treemap or stacked bar
Two-way movement between states over time	Chord diagram or slope chart

For a gallery of real budget, energy, and funnel Sankeys with the data behind them, see these Sankey diagram examples.

How Do You Read a Sankey Diagram Without Getting Fooled?

Read node heights first (total volume at each stage), then follow the widest links (dominant paths), and only then look at thin links. The common pitfalls: widths are only comparable within one diagram, not between two diagrams with different totals; long curved links look bigger than they are; and colors usually mean source category, not magnitude. Also check whether "exit" flows are drawn — a funnel Sankey that omits drop-offs overstates conversion.

What Tools Can Make a Sankey Diagram?

In JavaScript, the standard options are d3-sankey (full control, most work), Plotly.js (fastest to something interactive), ECharts (good defaults, built-in type: 'sankey'), and Google Charts. In Svelte or React, wrap d3-sankey for layout math and render the nodes/links yourself as SVG. Outside JS: Python Plotly (below), Power BI's built-in Sankey visual, and Flourish for no-code.

Tool	Best for	Effort
d3-sankey (D3)	Custom layouts, Svelte/React components	High
Plotly (JS or Python)	Interactive charts in minutes	Low
Apache ECharts	Dashboards, good default styling	Low
Power BI Sankey visual	BI reports, no code	Minimal

For working d3-sankey, Plotly.js, and ECharts code — including a Svelte wrapper pattern — see the full JavaScript Sankey diagram tutorial.

Creating a Sankey Diagram in Python (Plotly)

import plotly.graph_objects as go

# Website user flow: Landing → Pages → Actions
fig = go.Figure(data=[go.Sankey(
    node=dict(
        pad=15,
        thickness=20,
        label=["Homepage", "Product Page", "About", "Cart", "Checkout", "Purchase"],
        color=["blue", "orange", "green", "yellow", "red", "purple"]
    ),
    link=dict(
        source=[0, 0, 0, 1, 1, 3, 4],  # From node indices
        target=[1, 2, 3, 3, 4, 4, 5],  # To node indices
        value=[1000, 300, 500, 400, 300, 600, 200]  # Flow quantities
    )
)])

fig.update_layout(title="Website User Journey", font=dict(size=12))
fig.show()

Common Use Cases

Budget Allocation

# Company budget flow from revenue to expenses
nodes = ["Revenue", "Operating Costs", "Marketing", "R&D",
         "Salaries", "Infrastructure", "Advertising", "Social Media"]

links = {
    'source': [0, 0, 0, 1, 2, 2],  # Revenue splits to three departments
    'target': [1, 2, 3, 4, 6, 7],
    'value': [500000, 200000, 300000, 400000, 100000, 100000]
}

# Shows where money flows through organization

Customer Journey

# Marketing channel → Landing page → Conversion
source: ["Facebook", "Google", "Email", "Facebook", "Google", "Email"]
target: ["Landing A", "Landing A", "Landing B", "Convert", "Convert", "Convert"]
value: [1000, 1500, 800, 150, 300, 120]

# Visualizes conversion funnel from multiple sources

Energy Flow

# Energy production → consumption
Production sources → Distribution → End uses
Coal/Gas/Solar → Grid → Residential/Industrial/Commercial

Width shows proportion of total energy

Sankey Best Practices

• Arrange nodes logically (left to right flow)
• Use distinct colors for different categories
• Show values on hover for exact numbers
• Limit to 15-20 nodes for readability
• Ensure all flows sum correctly

Multi-Level Sankey

import plotly.graph_objects as go

# Traffic source → Landing page → Action → Outcome
fig = go.Figure(data=[go.Sankey(
    arrangement='snap',
    node={
        'label': [
            # Sources
            'Organic', 'Paid', 'Social',
            # Landing pages
            'Home', 'Product', 'Blog',
            # Actions
            'Browse', 'Add to Cart', 'Purchase'
        ],
        'color': ['#1f77b4'] * 3 + ['#ff7f0e'] * 3 + ['#2ca02c'] * 3
    },
    link={
        'source': [0,0,1,1,2,2, 3,3,4,4,5,5, 6,7,7],
        'target': [3,4,4,5,3,5, 6,7,6,7,6,8, 7,8,8],
        'value':  [500,300,400,200,300,100, 400,200,300,300,200,100, 100,150,250]
    }
)])

fig.update_layout(title="Multi-Stage User Journey")
fig.show()

When to Use Sankey Diagrams

• Showing flows between categories
• Visualizing proportional splits
• Tracking user journeys
• Budget/resource allocation
• Supply chain visualization