Sankey

A sankey draws a flow from one node to another. Each row is a link. The width of the ribbon is the amount. Nodes sit in columns, left to right, and a name sits on each node.

When to use it

Use a sankey when the question is where an amount goes, and a node can split or join. Acquisition flow sends ads and search through the landing page, the product page, and the blog, then on to trial and paid. Neighbourhood flows is one direction: Lantern feeds three docks.

A funnel is stages in one column. The width is how many remain at that step. A sankey is not that drop-off. A node can have several links in and several links out. Where the boats go, and come back also has a return: some boats come back, and those ribbons bow over the columns. A bar compares categories. It does not draw a path between them.

Sankey and funnel

Both can show a value getting smaller as it moves. The encoding is what changes.

type: "sankey" is a graph. encoding.source and encoding.target name the two ends of a link. encoding.y is the width. The chart builds the columns from the links.

type: "funnel" is one sequence. Each row is a stage and a size. There is no link to a second node, and a stage does not split. A tree is who connects to whom. It is not a weighted flow, and a node there has one parent.

Data

Each row is one link. Point encoding.source at the node it leaves and encoding.target at the node it enters. Point encoding.y at the amount. That amount is the ribbon width. Acquisition flow uses from, to, and flow. Neighbourhood flows uses trips. Where the boats go, and come back uses crossings.

A link from a node to itself is skipped. A missing amount, or an amount that is not positive, is skipped. A cycle stays in the graph. The return is a ribbon over the columns, not another column. Where the boats go, and come back is that chart.

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

A spec that renders

This is the smallest sankey. version, type, and a11y.alt are required. Two links, three nodes. The columns and the ribbon shape come from the graph, so mark can be omitted. The node names are the labels. There is no legend.

spec.json
{
  "version": "1",
  "type": "sankey",
  "data": [
    {
      "source": "Ads",
      "target": "Landing",
      "value": 40
    },
    {
      "source": "Landing",
      "target": "Paid",
      "value": 18
    }
  ],
  "encoding": {
    "source": "source",
    "target": "target",
    "y": "value"
  },
  "a11y": {
    "alt": "Ads reach paid through the landing page."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/sankeyBundle@chartkitdev/core/extraFamilyStatistical
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

The option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing sankey specs. Acquisition flow is the core example, ten links and no return. Neighbourhood flows is one direction between docks. Where the boats go, and come back draws the return ribbons.

Tooltip

tooltip is on for a sankey when the key is omitted. Hovering a node shows its name and the flow through it. Hovering a link shows the two ends and the amount. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows in the card, and tooltip.position places it. Change those in the playground. Turning the card off and on again puts that object back. An example that omitted tooltip gets the key removed, so the default stays on.

The rest of the spec

Node width, the gap between nodes, and where a column sits are not spec keys. The chart places them. encoding.color does not recolor a node. A legend is not drawn, because the name is already on the node. Theme presets live on the playground, with the full option list. Mermaid sankey syntax converts with fromMermaid.