Charts

Sankey

A Sankey flow diagram showing weighted directional relationships between nodes.

import { Sankey } from "metricui";

Use Sankey for flow analysis — traffic sources to conversions, budget allocation, user journey paths, energy distribution. For sequential stage conversion, use Funnel; for hierarchical part-to-whole, use Treemap.

Basic Example

Traffic Flow: Source to Conversion

<Sankey
  data={{
    nodes: [
      { id: "Organic Search" },
      { id: "Paid Ads" },
      { id: "Landing Page" },
      { id: "Signup" },
      { id: "Bounce" },
      // ...
    ],
    links: [
      { source: "Organic Search", target: "Landing Page", value: 4200 },
      { source: "Paid Ads", target: "Landing Page", value: 3100 },
      { source: "Landing Page", target: "Signup", value: 3800 },
      { source: "Landing Page", target: "Bounce", value: 4000 },
      // ...
    ],
  }}
  title="Traffic Flow: Source to Conversion"
  format="number"
  height={400}
/>

Custom Node Colors

Pass a colors array to control node coloring. Colors are assigned in order of node appearance.

Acquisition Funnel

<Sankey
  data={simpleFlow}
  title="Acquisition Funnel"
  format="number"
  colors={["#6366F1", "#8B5CF6", "#F59E0B", "#10B981", "#EF4444"]}
  height={300}
/>

Link Opacity

Adjust linkOpacity to control link transparency. Lower values help when many links overlap; higher values make individual flows easier to trace.

High Contrast Links

<Sankey
  data={simpleFlow}
  title="High Contrast Links"
  format="number"
  linkOpacity={0.7}
  nodeThickness={24}
  nodePadding={16}
  height={300}
/>

Props

Prop	Type	Default	Description
`data`	`SankeyData \| DataRow[]`	—	Native { nodes, links } format or flat DataRow[] with source/target/value columns.
`sourceField`	`string`	`"source"`	Column name for the source node (flat format).
`targetField`	`string`	`"target"`	Column name for the target node (flat format).
`valueField`	`string`	`"value"`	Column name for the link value (flat format).
`title`	`string`	—	Chart card title.
`subtitle`	`string`	—	Chart card subtitle.
`description`	`string \| React.ReactNode`	—	Description popover content.
`footnote`	`string`	—	Footnote.
`action`	`React.ReactNode`	—	Action slot.
`format`	`FormatOption`	—	Format for value labels and tooltips.
`height`	`number`	`300`	Chart height in px.
`colors`	`string[]`	—	Node colors.
`animate`	`boolean`	`true`	Enable/disable animation.
`nodeThickness`	`number`	`18`	Thickness of each node rect.
`nodePadding`	`number`	`12`	Vertical padding between nodes.
`linkOpacity`	`number`	`0.4`	Opacity of the links.
`legend`	`boolean \| LegendConfig`	—	Legend configuration.
`crossFilter`	`boolean \| { field?: string }`	—	Enable cross-filtering. true uses source as the field.
`drillDown`	`true \| ((event: { id: string; source?: string; target?: string; value?: number }) => React.ReactNode)`	—	Drill-down on node click. true = auto table, function = custom content.
`drillDownMode`	`"slide-over" \| "modal"`	`"slide-over"`	Drill-down presentation mode.
`tooltipHint`	`boolean \| string`	—	Tooltip action hint.
`variant`	`CardVariant`	—	Card variant.
`dense`	`boolean`	—	Compact layout.
`className`	`string`	—	Additional CSS class names.
`classNames`	`{ root?: string; header?: string; chart?: string; body?: string; legend?: string }`	—	Sub-element class name overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id.
`loading`	`boolean`	—	Loading state.
`empty`	`EmptyState`	—	Empty state configuration.
`error`	`ErrorState`	—	Error state configuration.
`stale`	`StaleState`	—	Stale data indicator.

Data Shape

// Nivo-native format
interface SankeyData {
  nodes: { id: string }[];
  links: { source: string; target: string; value: number }[];
}

// Flat-row format (converted via sourceField + targetField + valueField)
const rows = [
  { source: "Google",  target: "Landing Page", value: 5000 },
  { source: "Direct",  target: "Landing Page", value: 3000 },
  { source: "Landing Page", target: "Signup", value: 4200 },
];

Notes

Uses forwardRef.
Accepts two data modes: Nivo-native { nodes, links } or flat DataRow[] with source/target/value fields.
Node labels are positioned outside the node with horizontal orientation. At narrow widths (<500px), margins shrink automatically.
Link gradient is enabled by default — links blend from source to target color.
Install @nivo/sankey as a peer dependency.
The aiContext prop (inherited from BaseComponentProps) adds business context for AI Insights analysis. See the AI Insights guide for details.