Sankey Chart

Sankey charts visualize flow quantities between nodes. The width of each link is proportional to the flow quantity, making them ideal for showing energy transfers, budget flows, or user navigation paths.

Interface

SankeyChart Props

interface SankeyChartProps {
  // Required properties
  data: SankeyChartData;

  // Optional properties
  custom?: Partial<SankeyChartCustom>;
  title?: string;
}

Data Structure

type SankeyChartData = {
  nodes: {
    id: string;         // Unique node identifier
    label: string;      // Display label
    color?: string;     // Optional custom color
  }[];
  links: {
    source: string;     // Source node id
    target: string;     // Target node id
    value: number;      // Flow quantity
  }[];
  title?: string;       // Chart title
};

Basic Usage

import Widget from '@meursyphus/flitter-react';
import { SankeyChart } from '@meursyphus/headless-chart';

const data = {
  nodes: [
    { id: 'solar', label: 'Solar' },
    { id: 'wind', label: 'Wind' },
    { id: 'hydro', label: 'Hydro' },
    { id: 'electricity', label: 'Electricity' },
    { id: 'residential', label: 'Residential' },
    { id: 'commercial', label: 'Commercial' }
  ],
  links: [
    { source: 'solar', target: 'electricity', value: 100 },
    { source: 'wind', target: 'electricity', value: 80 },
    { source: 'hydro', target: 'electricity', value: 60 },
    { source: 'electricity', target: 'residential', value: 150 },
    { source: 'electricity', target: 'commercial', value: 90 }
  ],
  title: 'Energy Flow'
};

function BasicSankeyChart() {
  return (
    <Widget
      width="700px"
      height="400px"
      widget={SankeyChart({ data })}
    />
  );
}

Chart Components

Sankey Chart consists of the following hierarchical structure:

SankeyChart
└── Layout (overall layout)
    ├── Title (chart title)
    └── Sankey (sankey diagram area)
        ├── Node (individual nodes)
        ├── Link (flow connections)
        └── NodeLabel (node labels)

Customizable Elements

You can customize the following components through the custom prop:

Component	Args	Description
`layout`	`{ title, sankey }`	Overall chart layout
`sankey`	`{ nodes, links, nodeLabels }`	Sankey diagram container
`node`	`{ id, label, color, x, y, width, height }`	Individual node rectangle
`link`	`{ source, target, value, sourceX, sourceY, sourceHeight, targetX, targetY, targetHeight, color }`	Flow connection between nodes
`nodeLabel`	`{ id, label, x, y, width, height, column, totalColumns }`	Node label text
`title`	`{ name }`	Chart title

Real-World Usage Examples

1. Custom Node Colors

const coloredSankey = SankeyChart({
  data: {
    nodes: [
      { id: 'solar', label: 'Solar', color: '#f59e0b' },
      { id: 'wind', label: 'Wind', color: '#3b82f6' },
      { id: 'electricity', label: 'Electricity', color: '#8b5cf6' },
      { id: 'residential', label: 'Residential', color: '#10b981' }
    ],
    links: [
      { source: 'solar', target: 'electricity', value: 100 },
      { source: 'wind', target: 'electricity', value: 80 },
      { source: 'electricity', target: 'residential', value: 180 }
    ]
  }
});

2. Custom Link Style

const styledSankey = SankeyChart({
  data,
  custom: {
    link: ({ source, target, value, color }) => {
      // Custom curved link rendering with opacity based on value
    }
  }
});

Next Steps

For more examples, check out the demo page
Use color coding to group related flows
Add tooltips to show exact flow quantities