ApexSankey

A JavaScript library to create Sankey diagrams built on SVG

Dependency

Include svg.js

<script src="https://cdn.jsdelivr.net/npm/@svgdotjs/svg.js"></script>

Installation

To add the ApexSankey to your project and its dependencies, install the package from npm.

npm install apexsankey

Usage

import ApexSankey from 'apexsankey';

To create a basic sankey with minimal configuration, write as follows:

<div id="sankey-container"></div>

 const data = {
   ...(data with format provided below)
 }
 const options = {
    width: 800,
    height: 800,
    canvasStyle: 'border: 1px solid #caced0; background: #f6f6f6;',
    spacing: 100,
    nodeWidth: 20,
 };
 const sankey = new ApexSankey(document.getElementById('sankey-container'), options);
 const graph = sankey.render(data);

Setting the License

To use ApexSankey with a commercial license, set your license key before creating any chart instances:

import ApexSankey from 'apexsankey';

// set license key before creating any charts
ApexSankey.setLicense('your-license-key');

const sankey = new ApexSankey(document.getElementById('sankey-container'), options);
const graph = sankey.render(data);

ApexSankey Options

The layout can be configured by passing a second argument to ApexSankey with the properties listed below.

Option	Type	Default	Description
width	number | string	'100%'	Width of the canvas. Accepts a pixel number or CSS percentage string.
height	number | string	'auto'	Height of the canvas. 'auto' derives height from width at a 1.6:1 ratio.
canvasStyle	string	built-in border	Arbitrary CSS injected onto the SVG root container element.
spacing	number	20	Horizontal spacing between node columns in pixels.
nodeWidth	number	20	Width of each node rectangle in pixels.
nodeBorderWidth	number	1	Border width of each node in pixels.
nodeBorderColor	string | null	null	CSS color for the node border. null disables the border.
onNodeClick	(node: SankeyNode) => void	undefined	Callback fired when the user clicks a node.
edgeOpacity	number	0.4	Opacity of edges (0–1).
edgeGradientFill	boolean	true	Fill edges with a gradient between source and target node colors.
edgeGap	number	2	Gap in pixels between adjacent edges at node connection points.
whitespace	number	0.18	Fraction of vertical space used as margins between nodes (0–1). Lower = taller nodes.
viewPortWidth	number	800	Internal SVG viewport width in pixels.
viewPortHeight	number	500	Internal SVG viewport height in pixels.
highlightConnectedPath	boolean	true	Highlight the connected flow path when hovering a node or edge.
dimOpacity	number	0.2	Opacity for dimmed (unrelated) elements when path highlighting is active.
animation	{ enabled: boolean, duration: number }	{ enabled: true, duration: 800 }	Entrance animation. Automatically disabled when prefers-reduced-motion is set.
enableTooltip	boolean	true	Show edge tooltips on hover.
enableToolbar	boolean	true	Show the zoom/pan toolbar.
tooltipId	string	'apexsankey-tooltip-container'	HTML id for the tooltip container element.
tooltipTemplate	(content: TooltipContent) => string	built-in	Custom function returning an HTML string for the edge (source→target) tooltip.
nodeTooltipTemplate	(content: NodeTooltipContent) => string	built-in	Custom function returning an HTML string for the per-node tooltip.
tooltipTheme	'light' | 'dark'	undefined	Overrides tooltipBGColor/tooltipBorderColor/tooltipFontColor with a preset.
tooltipBorderColor	string	'#E2E8F0'	Border color of the tooltip.
tooltipBGColor	string	'#FFFFFF'	Background color of the tooltip.
tooltipFontColor	string	'#1a1a1a'	Font color inside the tooltip.
fontColor	string	'#212121'	CSS color for node labels.
fontFamily	string	''	CSS font-family for node labels. Falls back to the page default when empty.
fontSize	string	'14px'	CSS font-size for node labels.
fontWeight	string	'400'	CSS font-weight for node labels.
a11y	{ enabled?: boolean, diagramLabel?: string, description?: string }	{ enabled: true }	WCAG 2.1 AA accessibility options.

Default tooltip template

const tooltipTemplate = ({source, target, value}) => {
    return `
      <div style='display:flex;align-items:center;gap:5px;'>
        <div style='width:12px;height:12px;background-color:${source.color}'></div>
        <div>${source.title}</div>
        <div>=></div>
        <div style='width:12px;height:12px;background-color:${target.color}'></div>
        <div>${target.title}</div>
        <div>: ${value}</div>
      </div>
    `;
  },

Expected data format

Passed data should be an object containing nodes, edges and options. Nodes, edges and options should be in below format.

• nodes : Passed node object should contain id and title. Id is for uniquely identifying nodes and title is for node titles. It will be also used for showing tooltips for node-to-node connections.

{
  "id": "1", // required
  "title": "A" // required
}

• edges : Passed edge object should contain source, target, value and type. source is id value of source node for edge, target is id value of target node for edge, value indicates edge size and type is for grouping nodes.

{
    "source": "a",    // required
    "target": "b",    // required
    "value": 1,       // required
    "type": "x",      // optional
},

• options : ApexSankey supports two options order and alightLinkTypes.

  • order: optional list of layers

    If order is not specified, the nodes are automatically assigned to layers. If order is specified, it is used directly and no rank assignment or ordering algorithm takes place.

    The order structure has three nested lists: order is a list of layers, each of which is a list of bands, each of which is a list of node ids. For example,

    {
        "order": [
            [["a", "b"]],
            [["c"]],
        ],
    },

  • alignLinkTypes: boolean (default false). Whether to align link types across nodes, or order links to minimise crossings.

Example

const data = {
  nodes: [
    {
      id: 'a',
      title: 'AAA',
    },
    {
      id: 'b',
      title: 'BBB',
    },
    {
      id: 'c',
      title: 'CCC',
    },
  ],
  edges: [
    {
      source: 'a',
      target: 'c',
      value: 1,
      type: 'A',
    },
    {
      source: 'b',
      target: 'c',
      value: 2,
      type: 'A',
    },
  ],
  options: {
    order: [[['a', 'b']], [['c']]],
  },
};