# SankeyChart

> Sankey diagram: flows between columns of nodes, band widths proportional to the value.

Source: https://ui.jcsoftdev.com/docs/components/sankey-chart

Sankey diagram: flows between columns of nodes, band widths proportional to
the value. Hover (or keyboard) a node to follow its flows upstream and
downstream, or a link to isolate it; the tooltip gives value and share.

## Import

```ts
import { SankeyChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/sankey-chart`.

## Usage

```tsx
<SankeyChart
  title="Origen de clientes, servicio y medio de pago"
  nodes={nodes}
  links={links}
  columns={["Origen", "Servicio", "Pago"]}
  valueFormat="integer"
  height={400}
  nodePadding={14}
  align="justify"
  iterations={6}
  linkColor="gradient"
  linkOpacity={0.38}
  labelPosition="outside"
  showValues
  tooltip
  animate
  loading={false}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  | Accessible name of the drawing and caption of the data table. |
| `nodes` * | `readonly SankeyNodeInput[]` |  |  |
| `links` * | `readonly SankeyLinkInput[]` |  | Flows between node ids. Links that close a cycle are left out (with a dev warning). |
| `compare` | `readonly SankeyLinkInput[]` |  | Diff view: the flows of a previous period. `links` is then the current period; every band is colored by its change (`--chart-up` / `--chart-down`) with the previous width as a ghost behind it. |
| `pathTracing` | `boolean` |  | Hover or click traces a whole path: a link lights everything upstream of its source and downstream of its target; a click pins it. |
| `particles` | `boolean` |  | Dots travel along the bands (off under `prefers-reduced-motion`). |
| `exportable` | `boolean` | `false` | Show SVG and PNG export buttons above the drawing. |
| `legendItems` | `readonly { id: string; name: string; color: string; }[]` |  | Legend entries below the drawing; the nodes by default (an alluvial lists its categories). |
| `relax` | `boolean` |  | `false` keeps nodes in input order inside their column (see `AlluvialChart`). |
| `columns` | `readonly string[]` |  | Titles drawn above the columns, left to right, e.g. ["Origen", "Servicio", "Pago"]. |
| `height` | `number \| "fill"` | `380` |  |
| `aspectRatio` | `number` |  | Width / height ratio of the drawing; ignored with `"fill"`. |
| `valueFormat` | `ValueFormat` |  |  |
| `nodeWidth` | `number` |  | Thickness of the node bars (wider by default with inside labels). |
| `nodePadding` | `number` |  | Vertical gap between nodes of a column. |
| `align` | `"left" \| "justify"` |  | `justify` puts the final nodes in the last column; `left` keeps each at its depth. |
| `iterations` | `number` |  | Relaxation sweeps of the layout; more untangles more, at a cost. |
| `linkColor` | `"source" \| "target" \| "neutral" \| "gradient"` |  | `gradient` blends source into target; `source`/`target` use one end; `neutral` is grey. |
| `linkOpacity` | `number` |  | Resting opacity of the links (0-1). |
| `labelPosition` | `"outside" \| "inside"` |  | Node labels beside the bars (`outside`) or on wide bars (`inside`). |
| `showValues` | `boolean` |  | Value after each node label. |
| `tooltip` | `boolean` |  |  |
| `animate` | `boolean` |  |  |
| `loading` | `boolean` |  |  |
| `labels` | `Partial<SankeyLabels>` |  |  |
| `onNodeClick` | `((node: SankeyNode) => void)` |  |  |
| `onLinkClick` | `((link: SankeyLink) => void)` |  |  |
| `onRemovedLinks` | `((removed: SankeyGraph["removed"]) => void)` |  | Links the layout left out (cycles, self links, unknown ids, invalid values). |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-sankeychart--default)
- [Source Colored](/storybook/?path=/story/charts-sankeychart--source-colored)
- [Inside Labels](/storybook/?path=/story/charts-sankeychart--inside-labels)
- [Revenue](/storybook/?path=/story/charts-sankeychart--revenue)
- [With Cycle](/storybook/?path=/story/charts-sankeychart--with-cycle)
- [Loading](/storybook/?path=/story/charts-sankeychart--loading)
- [Empty](/storybook/?path=/story/charts-sankeychart--empty)
- [Narrow](/storybook/?path=/story/charts-sankeychart--narrow)
- [Fill Parent](/storybook/?path=/story/charts-sankeychart--fill-parent)
- [Alluvial](/storybook/?path=/story/charts-sankeychart--alluvial)
- [Diff](/storybook/?path=/story/charts-sankeychart--diff)
- [Path Tracing](/storybook/?path=/story/charts-sankeychart--path-tracing)
- [Particles](/storybook/?path=/story/charts-sankeychart--particles)
- [Export](/storybook/?path=/story/charts-sankeychart--export)
- [Chord](/storybook/?path=/story/charts-sankeychart--chord)

## Source

`packages/ui/src/charts/sankey-chart/sankey-chart.tsx`