apexsankey

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);

ApexSankey Options

The layout can be configured by either setting the properties in the table below by passing a second arg to ApexSankey with these properties set. The latter takes precedence.

Options	Default	Description
width	800	The width of graph container
height	800	The height of graph container
canvasStyle	None	The css styles for canvas root container
spacing	100	The spacing from top and left of graph container
nodeWidth	20	The width of graph nodes
nodeBorderWidth	1	The border width of the nodes in pixels
nodeBorderColor	none	The border color of the nodes
onNodeClick	empty function	The callback function for node click. Node object will be parameter for callback.
edgeOpacity	0.4	The opacity value for edges. Values must be between 0 to 1 and in fraction.
enableTooltip	false	Enable tooltip on hover of nodes
tooltipId	sankey-tooltip-container	The tooltip HTML element id
tooltipTemplate	tooltipTemplate	The HTML template for tooltip
tooltipBorderColor	#BCBCBC	The border color of tooltip
tooltipBGColor	#FFFFFF	The background color of tooltip
fontSize	14px	The size of font of nodes
fontFamily	None	The font family of nodes
fontWeight	400	The font weight of nodes
fontColor	#000000	The font color of nodes

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"]]],
  },
};