Sankey

A sankey answers "where does it all go" — how a quantity splits, drops off and recombines on its way through a set of stages. Give sankey one row per flow and say which fields hold the two ends and the amount. The nodes are whatever the links name, and each ribbon's thickness is its share of the total.

A sankey is the whole chart rather than a layer on one: it brings its own layout, so there are no axes to share and no other marks beside it.

Naming and coloring nodes

Pass nodes when the keys in your data aren't what a reader should see, or when an outcome deserves a fixed color rather than the next one in the palette. Naming a node changes nothing else on the chart — the rest keep the colors they had.

nodeLabel puts the node's own total beside its name, which is worth doing since a sankey has no value axis to read the sizes against — it is handed formattedValue, the total written the way valueFormat writes the tooltip's, so the two can't disagree.

Reading down the page

orientation: 'vertical' runs the flow top to bottom instead of left to right. It suits a funnel, where stages losing volume read as falling, and a chart with more height than width to spend. Horizontal suits long node names, which have room to sit beside their nodes rather than stacking above them.

Following a path

A sankey is read by following a path, so pointing at it dims whatever the reader isn't asking about. Point at a node and it stays lit along with every flow through it and the nodes at the far end of those flows — the whole of where this came from and where it goes. Point at a flow and it stays lit along with the two nodes it joins, while the other flows through those nodes recede, because the question there is that one path rather than everything around it.

Only what the pointer is actually on counts: inside a node's rectangle, or inside the band a flow paints. Empty space between flows focuses nothing rather than answering with whichever ribbon happened to be closest.

Nodes answer the pointer as well as the flows: hovering one opens a tooltip with its own total. The keyboard walks the flows alone, since they carry the quantities and stepping through every node as well would double the length of the walk without adding a reading.

This is on by default. Pass withUnfocusedDim: false for a chart that is a fixed picture rather than something to trace.

Rows that describe no flow — a missing end, a value that isn't a number at or above zero, a node pointed at itself — are left out rather than drawn, so one bad row from a query doesn't cost the reader the rest. A flow that loops back on itself has no left-to-right reading at all, and a chart whose links form a cycle draws an empty plot.