Skip to content
🚀 Influence MUI's 2026 roadmap! Take our latest Developer Survey
+

Charts - Sankey

Use Sankey charts to show how values flow between nodes, with link width proportional to magnitude.

Overview

A Sankey chart is a flow diagram that shows how values move between nodes. Links connect sources to targets, and link width shows how large each flow is.

The demo below shows flow from revenue to net income in billions USD.

Microsoft FY 2025 Income Statement

Flow from Revenue to Net Income (in Billions USD)

Basics

Provide 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, the chart creates it automatically and uses its ID as the label.

Press Enter to start editing

Explicit nodes

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

Press Enter to start editing

Styling

Default node styles

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

import { SankeyChart } from '@mui/x-charts-pro/SankeyChart';

<SankeyChart
  height={300}
  series={{
    data: {
      // ... your data
    },
    nodeOptions: {
      color: '#1976d2',
      width: 15,
      padding: 10,
      showLabels: true,
    },
  }}
/>

Playground

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

import { SankeyChart } from '@mui/x-charts-pro/SankeyChart';

<SankeyChart
  height={300}
  series={{
    data: {
      // ... your data
    },
    linkOptions: {
      color: '#90a4ae',
      opacity: 0.8,
      showValues: true,
    },
  }}
/>

Playground

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.

import { SankeyChart } from '@mui/x-charts-pro/SankeyChart';

<SankeyChart
  height={300}
  series={{
    data,
    linkOptions: {
      color: 'source',
      opacity: 0.6,
    },
  }}
/>

Playground

Node alignment

Node alignment controls how nodes are positioned:

  • The layout groups nodes into columns from the graph structure.
  • Source nodes always sit to the left of their targets.
  • Some nodes have a fixed column; moving them would add a column to the layout.
  • Others can sit 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

Left

Right

Justify

Center

Curve correction

The curveCorrection prop adjusts link curves by shifting the x-coordinate of control points. The effect depends on the graph layout and chart height. Higher values make links look thicker; lower values make them look thinner. The default is 10.

Curve Correction: 10
Press Enter to start editing

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 includes 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 you omit nodes, they render in the order they first 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
auto (default)
fixed
Custom Function

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
auto (default)
fixed
Custom Function

Layout iterations

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

import { SankeyChart } from '@mui/x-charts-pro/SankeyChart';

<SankeyChart
  height={400}
  series={{
    data: {
      // ... your data
    },
    iterations: 32,
  }}
/>

Playground

Interaction

Click events

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 you handle both in one callback.

Click on the chart

// Data from item click
// The data will appear here

Highlighting

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

Node Highlight
Node Fade
Link Highlight
Link Fade

Highlighting is configured separately for nodes and links.

Node highlighting

Use nodeOptions.highlight and nodeOptions.fade.

nodeOptions.highlight sets 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 sets how non-highlighted items are dimmed:

  • 'global': fade non-highlighted items
  • 'none': turn fading off

Link highlighting

Use linkOptions.highlight and linkOptions.fade.

linkOptions.highlight sets 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 sets how non-highlighted items are dimmed:

  • 'global': fade non-highlighted items
  • 'none': turn fading off

Controlled highlighting

Use the highlightedItem and onHighlightChange props to control highlighting from outside. Use this pattern when you want to highlight specific items programmatically or keep the chart in 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 updates).

Tooltip

The default Sankey tooltip is item-based. You can customize it with slots. See Tooltip for details.

The Sankey package exports the default tooltip and its content if you want to reuse or extend them:

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

Composition

Use SankeyDataProvider to provide the series prop for composition.

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

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

Here's how the Sankey chart is composed:

<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.