Charts - Sankey

Show flows between nodes as connected links with proportional widths.

Overview

A Sankey chart is a flow diagram that shows how values move between nodes. Links connect source nodes to target nodes, and link width represents the flow magnitude.

Basics

The Sankey chart expects a data structure with nodes and links.

• nodes: optional array for customizing individual nodes (labels, colors)
• links: required array of connections, each with source, target, and value

Automatic nodes

If a node appears in links but not in nodes, it is created automatically with its ID as the label.

Explicit nodes

When you define nodes in the nodes array, you can set labels and colors for each.

Styling

Default node styles

Use the nodeOptions prop to apply default styles to all nodes.

Default link styles

Use the linkOptions prop to apply default styles to all links.

Link color keywords

Link colors can use 'source' to inherit from the source node or 'target' to inherit from the target node.

This works for individual link colors and for the default in linkOptions.

Node alignment

Node alignment controls how nodes are positioned. The layout groups nodes into columns based on the graph structure. Source nodes are always left of their targets. Some nodes have fixed positions (from the graph topology). Others can be placed in different columns depending on alignment.

In the demo below:

• Nodes A, B, D, G, I, and K have fixed positions (moving them would add a column)
• Node E can sit in the first or second column
• Node F can sit in columns 4, 5, or 6

Curve correction

The curveCorrection prop adjusts how links look by changing the x-coordinate of curve control points. The result depends on the graph layout and chart height. Higher values make links thicker, and lower values make them thinner. The default is 10.

Value formatting

Use the valueFormatter prop to customize how values appear in tooltips and labels. The formatter receives the numeric value and a context object. The context has location ('tooltip' or 'label'), type ('node' or 'link'), and for nodes nodeId, for links sourceId and targetId.

The demo below adds units to values and shows "total" when the pointer is over a node.

Sorting

Nodes render in the order of the nodes array. If nodes is not provided, they render in the order they appear in links. Use the sorting options to change the order.

Node sorting

The nodeOptions.sort property controls the vertical order of nodes in each column. It accepts:

• A function that receives two SankeyLayoutNode objects and returns a number (like Array.sort())
• 'auto' (default): automatic sorting to reduce link crossings
• 'fixed': keep the order from the nodes array

Link sorting

The linkOptions.sort property controls the order of links leaving each node. It accepts:

• A function that receives two SankeyLayoutLink objects and returns a number
• 'auto' (default): automatic sorting to reduce link crossings
• 'fixed': keep the order from the links array

Layout iterations

The iterations prop sets how many times the layout algorithm runs. More iterations usually improve the layout but take longer.

Interaction

Click event

Use the onNodeClick and onLinkClick props to handle clicks on nodes and links. Each callback receives the mouse event and an identifier object (SankeyNodeIdentifierWithData or SankeyLinkIdentifierWithData) with details about the clicked item. Use SankeyItemIdentifierWithData when handling both in one callback.

Highlighting

You can highlight nodes and links by hovering or programmatically. When an item is highlighted, others can be faded to improve focus.

Highlighting is configured separately for nodes and links.

Node highlighting

Use nodeOptions.highlight and nodeOptions.fade:

• nodeOptions.highlight: what to highlight when a node is selected
  • 'nodes': only the selected node
  • 'links': all links connected to the node
  • 'incoming': only incoming links
  • 'outgoing': only outgoing links
  • 'none': no highlighting
• nodeOptions.fade: 'global' fades non-highlighted items, 'none' turns fade off

Link highlighting

Use linkOptions.highlight and linkOptions.fade:

• linkOptions.highlight: what to highlight when a link is selected
  • 'links': only the selected link
  • 'nodes': source and target nodes
  • 'source': only the source node
  • 'target': only the target node
  • 'none': no highlighting
• linkOptions.fade: 'global' or 'none'

Controlled highlighting

Use the highlightedItem and onHighlightChange props to control highlighting from outside. This helps when you want to highlight specific items programmatically or sync with other UI.

The highlightedItem prop accepts a SankeyNodeIdentifier or SankeyLinkIdentifier:

For nodes:

{
  type: 'sankey',
  seriesId: string,
  subType: 'node',
  nodeId: string | number,
}

For links:

{
  type: 'sankey',
  seriesId: string,
  subType: 'link',
  sourceId: string | number,
  targetId: string | number,
}

The onHighlightChange callback runs when the highlighted item changes (from user interaction or programmatic control).

Tooltip

The Sankey chart has an item tooltip that you can customize as described in the Tooltip documentation. The Sankey tooltip differs only in its default content.

Import the default tooltip or its content:

import { SankeyTooltip, SankeyTooltipContent } from '@mui/x-charts/SankeyChart';

Composition

Use SankeyDataProvider to supply the series prop when composing a custom chart.

In addition to the shared components available for composition, you can use:

• For items: SankeyNodePlot, SankeyLinkPlot
• For labels: SankeyNodeLabelPlot, SankeyLinkLabelPlot
• For keyboard: FocusedSankeyNode, FocusedSankeyLink

The following code shows how the Sankey chart is built:

<SankeyDataProvider series={series as SankeySeriesType[]} {...chartDataProviderProProps}>
  <ChartsWrapper {...chartsWrapperProps}>
    <ChartsSurface {...chartsSurfaceProps}>
      <SankeyLinkPlot onClick={onLinkClick} />
      <SankeyNodePlot onClick={onNodeClick} />

      <SankeyLinkLabelPlot />
      <SankeyNodeLabelPlot />

      <FocusedSankeyNode />
      <FocusedSankeyLink />

      <ChartsOverlay {...overlayProps} />
    </ChartsSurface>
    <ChartsTooltip trigger="item" />
  </ChartsWrapper>
</SankeyDataProvider>

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <FocusedSankeyLink />
• <FocusedSankeyNode />
• <SankeyChart />
• <SankeyDataProvider />
• <SankeyPlot />
• <SankeyTooltip />
• <SankeyTooltipContent />