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.
{
"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.
npm install @chartkitdev/core
npm install @chartkitdev/react
import { Chart } from "@chartkitdev/react";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/vanilla
import { mount } from "@chartkitdev/vanilla";
const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);npm install @chartkitdev/core
npm install @chartkitdev/vue
<script setup>
import { Chart } from "@chartkitdev/vue";
</script>
<template>
<Chart :spec="spec" />
</template>npm install @chartkitdev/core
npm install @chartkitdev/svelte
<script>
import { Chart } from "@chartkitdev/svelte";
</script>
<Chart {spec} />npm install @chartkitdev/core
npm install @chartkitdev/astro
---
import { Chart } from "@chartkitdev/astro";
---
<Chart spec={spec} />npm install @chartkitdev/core
npm install @chartkitdev/solid
import { Chart } from "@chartkitdev/solid";
export function Panel() {
return <Chart spec={spec} />;
}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} />;
});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;
}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": 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.