Sankey Chart · Kind UI charts

Loading chart…

Configured energy allocation (MWh)
Flow	Source ID	Target ID	MWh
solar-homes	solar	homes	35
solar-industry	solar	industry	25
wind-homes	wind	homes	15
wind-industry	wind	industry	25

example.tsx

"use client";
import * as Chart from "@kind-ui/charts";
import "@kind-ui/charts/styles.css";
import { Tooltip } from "recharts";

const data = {
  nodes: [
    { id: "solar", name: "Solar" },
    { id: "wind", name: "Wind" },
    { id: "homes", name: "Homes" },
    { id: "industry", name: "Industry" },
  ],
  links: [
    { id: "solar-homes", source: "solar", target: "homes", value: 35 },
    { id: "solar-industry", source: "solar", target: "industry", value: 25 },
    { id: "wind-homes", source: "wind", target: "homes", value: 15 },
    { id: "wind-industry", source: "wind", target: "industry", value: 25 },
  ],
} satisfies Chart.SankeyFlowData;
const nodeConfig = {
  solar: { label: "Solar", color: "#d29319" },
  wind: { label: "Wind", color: "#159c91" },
  homes: { label: "Homes", color: "#8865ce" },
  industry: { label: "Industry", color: "#447fd1" },
} satisfies Chart.SankeyNodeConfig;

export function ConfiguredFlowChart() {
  return (
    <section aria-label="Energy allocation">
      <Chart.ResponsiveContainer width="100%" height={250}>
        <Chart.SankeyChart data={data} nodeConfig={nodeConfig}>
          <Tooltip isAnimationActive={false} formatter={(value) => `${value} MWh`} />
        </Chart.SankeyChart>
      </Chart.ResponsiveContainer>
      <Chart.SankeyLegend config={nodeConfig} />
    </section>
  );
}

Usage

SankeyChart validates balanced directed flows and delegates layout to Recharts. Share nodeConfig with SankeyLegend for default node/source-link colors and static metadata.

Composition

<Chart.ResponsiveContainer width="100%" height={250}>
  <Chart.SankeyChart
    data={data} nodeConfig={nodeConfig}
    animate={{ revealDurationMs: 900 }}
  >
    <Tooltip isAnimationActive={false} />
  </Chart.SankeyChart>
</Chart.ResponsiveContainer>
<Chart.SankeyLegend config={nodeConfig} />

Sankey needs no Root or axes. nodeConfig maps every node ID, including isolated/zero-only nodes, to a label and color. Default nodes use their own color; solid links use the source color. Import Tooltip from Recharts.

Identities and selection

Compose native node/link callbacks when labels, gradients or interaction need custom rendering.

Loading chart…

Illustrative energy allocation (MWh)
Flow	Source ID	Target ID	MWh
solar-north	solar	north	30
solar-central	solar	central	20
solar-south	solar	south	10
wind-north	wind	north	20
wind-central	wind	central	30
wind-south	wind	south	30
hydro-north	hydro	north	20
hydro-central	hydro	central	10
hydro-south	hydro	south	10
north-homes	north	homes	35
north-industry	north	industry	25
north-services	north	services	10
central-homes	central	homes	15
central-industry	central	industry	30
central-services	central	services	15
south-homes	south	homes	10
south-industry	south	industry	15
south-services	south	services	25

example.tsx

"use client";
import * as Chart from "@kind-ui/charts";
import "@kind-ui/charts/styles.css";
import { useState } from "react";
import { Tooltip } from "recharts";

const data = {
  nodes: [
    { id: "solar", name: "Solar" },
    { id: "wind", name: "Wind" },
    { id: "hydro", name: "Hydro" },
    { id: "north", name: "North" },
    { id: "central", name: "Central" },
    { id: "south", name: "South" },
    { id: "homes", name: "Homes" },
    { id: "industry", name: "Industry" },
    { id: "services", name: "Services" },
  ],
  links: [
    { id: "solar-north", source: "solar", target: "north", value: 30 },
    { id: "solar-central", source: "solar", target: "central", value: 20 },
    { id: "solar-south", source: "solar", target: "south", value: 10 },
    { id: "wind-north", source: "wind", target: "north", value: 20 },
    { id: "wind-central", source: "wind", target: "central", value: 30 },
    { id: "wind-south", source: "wind", target: "south", value: 30 },
    { id: "hydro-north", source: "hydro", target: "north", value: 20 },
    { id: "hydro-central", source: "hydro", target: "central", value: 10 },
    { id: "hydro-south", source: "hydro", target: "south", value: 10 },
    { id: "north-homes", source: "north", target: "homes", value: 35 },
    { id: "north-industry", source: "north", target: "industry", value: 25 },
    { id: "north-services", source: "north", target: "services", value: 10 },
    { id: "central-homes", source: "central", target: "homes", value: 15 },
    { id: "central-industry", source: "central", target: "industry", value: 30 },
    { id: "central-services", source: "central", target: "services", value: 15 },
    { id: "south-homes", source: "south", target: "homes", value: 10 },
    { id: "south-industry", source: "south", target: "industry", value: 15 },
    { id: "south-services", source: "south", target: "services", value: 25 },
  ],
} satisfies Chart.SankeyFlowData;
const nodeConfig = {
  solar: { label: "Solar", color: "#d29319" },
  wind: { label: "Wind", color: "#159c91" },
  hydro: { label: "Hydro", color: "#447fd1" },
  north: { label: "North", color: "#8865ce" },
  central: { label: "Central", color: "#d27559" },
  south: { label: "South", color: "#569951" },
  homes: { label: "Homes", color: "#d29319" },
  industry: { label: "Industry", color: "#447fd1" },
  services: { label: "Services", color: "#159c91" },
} satisfies Chart.SankeyNodeConfig;
const names = new Map(data.nodes.map((node) => [node.id, node.name]));

export function EnergyFlowChart() {
  const [active, setActive] = useState<string | null>(null);
  const selected = data.links.find((link) => link.id === active);
  return (
    <section aria-label="Illustrative energy allocation">
      <section
        aria-label="Energy flow diagram; scroll horizontally on small screens"
        // biome-ignore lint/a11y/noNoninteractiveTabindex: Horizontal chart scrolling is keyboard accessible.
        tabIndex={0}
        style={{ overflowX: "auto", overscrollBehaviorY: "auto" }}
      >
        <div style={{ minWidth: 540 }}>
          <div
            style={{
              display: "flex",
              justifyContent: "space-between",
              fontSize: 12,
              padding: "0 28px",
            }}
          >
            <span>Generation</span>
            <span>Balancing zones</span>
            <span>End use</span>
          </div>
          <Chart.ResponsiveContainer width="100%" height={250}>
            <Chart.SankeyChart
              data={data}
              nodeConfig={nodeConfig}
              animate={{ revealDurationMs: 900 }}
              nodeWidth={10}
              nodePadding={16}
              sort={false}
              margin={{ top: 28, right: 32, bottom: 8, left: 32 }}
              title="Energy allocation: 180 MWh across three stages"
              desc="Nine nodes and eighteen flows. Ribbon widths represent MWh. Select a flow with a click, Enter or Space; Escape clears selection."
              node={(props) => (
                <g>
                  <Chart.SankeyNode {...props} />
                  <text
                    x={props.x + props.width / 2}
                    y={props.y - 7}
                    textAnchor="middle"
                    fill="currentColor"
                    fontSize={11}
                  >
                    {props.payload.name}
                  </text>
                </g>
              )}
              link={(props) => (
                <Chart.SankeyLink
                  {...props}
                  material="gradient"
                  pathProps={{
                    role: "button",
                    tabIndex: 0,
                    "aria-label": `${props.payload.source.name} to ${props.payload.target.name}: ${props.payload.value} MWh`,
                    "aria-pressed": active === props.payload.id,
                    opacity: active && active !== props.payload.id ? 0.12 : 0.55,
                    onClick: () => setActive(active === props.payload.id ? null : props.payload.id),
                    onKeyDown: (event) => {
                      if (event.key === "Escape") setActive(null);
                      if (event.key === "Enter" || event.key === " ") {
                        event.preventDefault();
                        setActive(active === props.payload.id ? null : props.payload.id);
                      }
                    },
                  }}
                />
              )}
            >
              <Tooltip isAnimationActive={false} formatter={(value) => `${value} MWh`} />
            </Chart.SankeyChart>
          </Chart.ResponsiveContainer>
        </div>
      </section>
      <Chart.SankeyLegend config={nodeConfig} />
      <p role="status" style={{ fontSize: 12, margin: "8px 0 0" }}>
        {selected
          ? `${names.get(selected.source)} → ${names.get(selected.target)}: ${selected.value} MWh`
          : "180 MWh · Select a ribbon to inspect its route."}
      </p>
      <Chart.SankeyTable
        data={data}
        caption="Illustrative allocation in MWh"
        style={{
          position: "absolute",
          width: 1,
          height: 1,
          padding: 0,
          margin: -1,
          overflow: "hidden",
          clipPath: "inset(50%)",
          whiteSpace: "nowrap",
          border: 0,
        }}
      />
    </section>
  );
}

Give nodes and links unique nonempty string IDs. Endpoints accept IDs or original-array integer indices; numeric-looking strings remain IDs. Use renderer payload.id for stable application identity.

Click or press Enter/Space to select a ribbon; Escape clears it. Selection changes paint, not quantities. A hidden SankeyTable retains all routes; narrow diagrams scroll horizontally.

Intermediate inflow must equal outflow. Model losses/gains as explicit boundary links. This example carries 180 MWh per stage.

Flow finishes

Choose plain, paper, clay or glow with finish; material="gradient" resolves source and target colors from the same nodeConfig. Explicit color and targetColor remain overrides. Labels remain consumer-owned outside the filters.

Loading chart…

Illustrative energy allocation (MWh)
Flow	Source ID	Target ID	MWh
solar-north	solar	north	30
solar-central	solar	central	20
solar-south	solar	south	10
wind-north	wind	north	20
wind-central	wind	central	30
wind-south	wind	south	30
hydro-north	hydro	north	20
hydro-central	hydro	central	10
hydro-south	hydro	south	10
north-homes	north	homes	35
north-industry	north	industry	25
north-services	north	services	10
central-homes	central	homes	15
central-industry	central	industry	30
central-services	central	services	15
south-homes	south	homes	10
south-industry	south	industry	15
south-services	south	services	25

example.tsx

"use client";
import * as Chart from "@kind-ui/charts";
import "@kind-ui/charts/styles.css";
import { useState } from "react";
import { Tooltip } from "recharts";

const data = {
  nodes: [
    { id: "solar", name: "Solar" },
    { id: "wind", name: "Wind" },
    { id: "hydro", name: "Hydro" },
    { id: "north", name: "North" },
    { id: "central", name: "Central" },
    { id: "south", name: "South" },
    { id: "homes", name: "Homes" },
    { id: "industry", name: "Industry" },
    { id: "services", name: "Services" },
  ],
  links: [
    { id: "solar-north", source: "solar", target: "north", value: 30 },
    { id: "solar-central", source: "solar", target: "central", value: 20 },
    { id: "solar-south", source: "solar", target: "south", value: 10 },
    { id: "wind-north", source: "wind", target: "north", value: 20 },
    { id: "wind-central", source: "wind", target: "central", value: 30 },
    { id: "wind-south", source: "wind", target: "south", value: 30 },
    { id: "hydro-north", source: "hydro", target: "north", value: 20 },
    { id: "hydro-central", source: "hydro", target: "central", value: 10 },
    { id: "hydro-south", source: "hydro", target: "south", value: 10 },
    { id: "north-homes", source: "north", target: "homes", value: 35 },
    { id: "north-industry", source: "north", target: "industry", value: 25 },
    { id: "north-services", source: "north", target: "services", value: 10 },
    { id: "central-homes", source: "central", target: "homes", value: 15 },
    { id: "central-industry", source: "central", target: "industry", value: 30 },
    { id: "central-services", source: "central", target: "services", value: 15 },
    { id: "south-homes", source: "south", target: "homes", value: 10 },
    { id: "south-industry", source: "south", target: "industry", value: 15 },
    { id: "south-services", source: "south", target: "services", value: 25 },
  ],
} satisfies Chart.SankeyFlowData;
const nodeConfig = {
  solar: { label: "Solar", color: "#d29319" },
  wind: { label: "Wind", color: "#159c91" },
  hydro: { label: "Hydro", color: "#447fd1" },
  north: { label: "North", color: "#8865ce" },
  central: { label: "Central", color: "#d27559" },
  south: { label: "South", color: "#569951" },
  homes: { label: "Homes", color: "#d29319" },
  industry: { label: "Industry", color: "#447fd1" },
  services: { label: "Services", color: "#159c91" },
} satisfies Chart.SankeyNodeConfig;
const names = new Map(data.nodes.map((node) => [node.id, node.name]));

export function EnergyFlowFinishChart({ finish = "paper" }: { finish?: Chart.SankeyFinish }) {
  const [active, setActive] = useState<string | null>(null);
  const selected = data.links.find((link) => link.id === active);
  return (
    <section aria-label="Illustrative energy allocation">
      <section
        aria-label="Energy flow diagram; scroll horizontally on small screens"
        // biome-ignore lint/a11y/noNoninteractiveTabindex: Horizontal chart scrolling is keyboard accessible.
        tabIndex={0}
        style={{ overflowX: "auto", overscrollBehaviorY: "auto" }}
      >
        <div style={{ minWidth: 540 }}>
          <div
            style={{
              display: "flex",
              justifyContent: "space-between",
              fontSize: 12,
              padding: "0 28px",
            }}
          >
            <span>Generation</span>
            <span>Balancing zones</span>
            <span>End use</span>
          </div>
          <Chart.ResponsiveContainer width="100%" height={250}>
            <Chart.SankeyChart
              data={data}
              nodeConfig={nodeConfig}
              animate={{ revealDurationMs: 900 }}
              nodeWidth={10}
              nodePadding={16}
              sort={false}
              margin={{ top: 28, right: 32, bottom: 8, left: 32 }}
              title="Energy allocation: 180 MWh across three stages"
              desc="Nine nodes and eighteen flows. Ribbon widths represent MWh. Select a flow with a click, Enter or Space; Escape clears selection."
              node={(props) => (
                <g>
                  <Chart.SankeyNode {...props} finish={finish} />
                  <text
                    x={props.x + props.width / 2}
                    y={props.y - 7}
                    textAnchor="middle"
                    fill="currentColor"
                    fontSize={11}
                  >
                    {props.payload.name}
                  </text>
                </g>
              )}
              link={(props) => (
                <Chart.SankeyLink
                  {...props}
                  finish={finish}
                  material="gradient"
                  pathProps={{
                    role: "button",
                    tabIndex: 0,
                    "aria-label": `${props.payload.source.name} to ${props.payload.target.name}: ${props.payload.value} MWh`,
                    "aria-pressed": active === props.payload.id,
                    opacity: active && active !== props.payload.id ? 0.12 : 0.55,
                    onClick: () => setActive(active === props.payload.id ? null : props.payload.id),
                    onKeyDown: (event) => {
                      if (event.key === "Escape") setActive(null);
                      if (event.key === "Enter" || event.key === " ") {
                        event.preventDefault();
                        setActive(active === props.payload.id ? null : props.payload.id);
                      }
                    },
                  }}
                />
              )}
            >
              <Tooltip isAnimationActive={false} formatter={(value) => `${value} MWh`} />
            </Chart.SankeyChart>
          </Chart.ResponsiveContainer>
        </div>
      </section>
      <Chart.SankeyLegend config={nodeConfig} />
      <p role="status" style={{ fontSize: 12, margin: "8px 0 0" }}>
        {selected
          ? `${names.get(selected.source)} → ${names.get(selected.target)}: ${selected.value} MWh`
          : "180 MWh · Select a ribbon to inspect its route."}
      </p>
      <Chart.SankeyTable
        data={data}
        caption="Illustrative allocation in MWh"
        style={{
          position: "absolute",
          width: 1,
          height: 1,
          padding: 0,
          margin: -1,
          overflow: "hidden",
          clipPath: "inset(50%)",
          whiteSpace: "nowrap",
          border: 0,
        }}
      />
    </section>
  );
}

Motion and geometry

Entrance reveals supported link paint along fixed paths; widths and node positions stay unchanged. Interaction, data/layout/renderer changes or resize finish it; reduced motion skips it.

Recharts owns coordinates, control points and widths. Kind preserves computed geometry against presentation overrides. Small frames show a status when the padding budget cannot fit.

API reference

Focused public props; native SVG presentation and Recharts layout options remain available.

SankeyChart

Prop	Type	Default	Description
`data`	`SankeyFlowData`	Required	Immutable nodes and links; validates identities, quantities, acyclicity and intermediate balance.
`nodeConfig`	`SankeyNodeConfig`	Off	Explicit node-ID labels/colors; enables default Kind node and source-link paint.
`node`	Native object, element or `(props: SankeyNodeProps) => ReactNode`	Kind node with `nodeConfig`; otherwise native	Receives computed geometry and typed node identity.
`link`	Native object, element or native-compatible callback using `SankeyLinkProps`	Kind link with `nodeConfig`; otherwise native	Metadata enables default Kind paint/motion; custom callbacks retain control.
`animate`	`boolean \| { revealDurationMs?: number }`	`false`	Flow paint reveal; `true` uses 450ms. Duration must be finite and nonnegative.
`empty`	`ReactNode`	`"No positive flows"`	Status for empty or all-zero data.
`nodeWidth`	`number`	`10`	Native node rectangle width.
`nodePadding`	`number`	`10`	Native vertical gap between nodes.
`sort`	`boolean`	`true`	Native node ordering; these components use `false`.
`linkCurvature`	`number`	`0.5`	Native cubic link curvature.
`iterations`	`number`	`32`	Native layout relaxation iterations.
`margin`	`{ top?: number; right?: number; bottom?: number; left?: number }`	`5` each side	Reserve space for consumer labels.
`onClick` / `onMouseEnter` / `onMouseLeave`	`(item, type, event) => void`	—	Native event with typed node/link IDs; `type` is `"node" \| "link"`.
`children`	`ReactNode`	—	Native tooltip or other supported children.

Equal-value positive parallel links are rejected; distinct values are supported. Rescale extreme numeric ranges before native layout. See Recharts Sankey.

SankeyNode

Prop	Type	Default	Description
Native renderer geometry and `payload`	`SankeyNodeProps`	Required	Spread the complete callback props; computed rectangle dimensions win.
`color`	`string`	Config color; fallback `"#4f46e5"`	Explicit paint overrides metadata.
`finish`	`"plain" \| "paper" \| "clay" \| "glow"`	`"plain"`	Static surface filter; explicit filters take precedence.
`rectProps`	`SVGProps<SVGRectElement>`	—	Presentation, semantics and handlers on the original rectangle.

Supply node labels as sibling SVG text. Selection and legend state remain consumer-owned.

SankeyLink

Prop	Type	Default	Description
Native renderer geometry and `payload`	`SankeyLinkProps`	Required	Spread the complete callback props; path and flow width stay native.
`material`	`"solid" \| "gradient"`	`"solid"`	Single-color stroke or source-to-target gradient.
`color`	`string`	Source config color; fallback `"#4f46e5"`	Explicit source paint override.
`targetColor`	`string`	Target config color; fallback `"#06b6d4"`	Explicit destination override for gradient paint.
`finish`	`"plain" \| "paper" \| "clay" \| "glow"`	`"plain"`	Static treatment independent of material and flow width.
`pathProps`	`SVGProps<SVGPathElement>`	—	Presentation, keyboard handlers and semantics on the original path; computed geometry wins.

Explicit filters bypass finishes; transformed paths bypass reveal. Custom renderers own motion. Glow changes neither quantities nor hit targets.

SankeyLegend

A standalone static list; share the exact config passed to SankeyChart. Config insertion order determines legend order. It does not toggle or infer flows.

Prop	Type	Default	Description
`config`	`SankeyNodeConfig`	Required	Explicit node-ID labels/colors; extra entries remain visible in the legend.
`children`	`(item: { key: string; label: string; color: string; marker: ReactNode }) => ReactNode`	Label and marker	Custom legend content; native list attributes and refs remain available.

SankeyTable

Prop	Type	Default	Description
`data`	`SankeyFlowData`	Required	Complete input, including zero flows; validated independently.
`caption`	`string`	Required	Accessible table name.
`formatValue`	`(value: number) => string`	`String`	Consumer-owned units.
`onInspect`	`(link: SankeyFlowLink) => void`	—	Adds native inspection buttons receiving the original link.
`activeLinkId`	`string \| null`	—	Controlled selected row and button `aria-pressed`.

Native attributes/refs remain available. These examples hide the table; onInspect supports a visible keyboard inspector.

Flow data

Prop	Type	Default	Description
`nodes`	`readonly SankeyFlowNode[]`	Required	Each node has unique `id: string` and `name: string`; extra metadata is retained.
`links`	`readonly SankeyFlowLink[]`	Required	Each link has unique `id: string`, endpoints and a value.
`source` / `target`	`string \| number`	Required	Node ID or original node-array integer index.
`value`	`number`	Required	Finite nonnegative flow quantity.

prepareSankeyData(data) validates/copies input and resolves endpoints to indices. It does not aggregate, normalize or infer flows. Cycles, invalid endpoints/IDs and negative/nonfinite quantities throw.

Zero links remain in the table but leave plotted geometry; isolated nodes also leave the plot.

Shared components

ResponsiveContainer, Tooltip.

Sankey uses the native Recharts Tooltip for hover inspection. Path handlers and status text provide keyboard selection. Give the diagram a measurable height; these examples use a 540px minimum width.

UsageCopy Anchor Link

Identities and selectionCopy Anchor Link

Flow finishesCopy Anchor Link

Motion and geometryCopy Anchor Link

API referenceCopy Anchor Link

SankeyChartCopy Anchor Link

SankeyNodeCopy Anchor Link

SankeyLinkCopy Anchor Link

SankeyLegendCopy Anchor Link

SankeyTableCopy Anchor Link

Flow dataCopy Anchor Link

Shared componentsCopy Anchor Link

On this page

Usage

Identities and selection

Flow finishes

Motion and geometry

API reference

SankeyChart

SankeyNode

SankeyLink

SankeyLegend

SankeyTable

Flow data

Shared components