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

Methods

Methods available on an ApexSankey instance:

Method	Description
`render(data)`	Build the diagram from `data` (`{ nodes, edges }`) and write the SVG into the container. Returns the internal graph renderer, which exposes `exportToSvg()`.
`update(data)`	Transition an already-rendered instance to new `data`. When the new layout shares the current topology (same nodes and flows, only different values or positions), the nodes and ribbons spring smoothly to their new places. When the topology differs, it morphs through the change: entering flows grow out of their source node, survivors slide to their new places, and removed flows retract and dissolve. When animation is disabled or the user prefers reduced motion, it redraws instantly.
`ApexSankey.setLicense(key)`	Static. Set the commercial license key before creating any chart instances.
`ApexSankey.registerTheme(name, theme)`	Static. Register (or override) a named theme (a `SankeyTheme`), then reference it by name via the `theme` option. Use for brand presets.
`ApexSankey.collapseGroups(data, groups, collapsed)`	Static. Project a detailed `{ nodes, edges }` to an aggregated one by collapsing the listed groups into super-nodes (re-routing and merging their flows). The pure transform behind the `drillDown` plugin; use it to seed the initial collapsed render.
`ApexSankey.compare(element, config)`	Static. Render two linked diagrams (a "before" and an "after") side by side, outlining each flow by how it changed and highlighting the twin node or flow across both panels on hover. Returns a `SankeyComparison` handle (`before` / `after` / `diff` / `destroy()`). See Comparison split-view.
`on(event, handler)`	Subscribe to an instance event (see Plugins & Events). Returns an unsubscribe function.
`off(event, handler)`	Remove a handler previously registered with `on`.
`use(plugin)`	Install a `SankeyPlugin`. Its `install` runs immediately; any teardown it returns runs on `destroy()`. Returns the instance.
`destroy()`	Tear down the chart: run plugin teardowns, emit `destroyed`, drop all handlers, and remove injected DOM (tooltip container).

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.
`type`	`'sankey' \| 'chord'`	`'sankey'`	Which projection of the flow model to draw. `'chord'` renders a radial diagram (nodes as arcs on a ring, flows as ribbons across the interior) for dense many-to-many relationships. See Chord.
`arcCornerRadius`	`number`	`6`	Chord only. Corner radius (px) for the rounded outer corners of each node arc (the inner edge, where ribbons meet, stays flush). `0` gives sharp corners; clamped to the ring band width.
`theme`	`string \| SankeyTheme`	`undefined`	A named built-in theme (`'light'`, `'dark'`, `'midnight'`, `'mint'`, `'sunset'`), a name registered via `ApexSankey.registerTheme`, or an inline `SankeyTheme`. Seeds coordinated visual defaults (palette, colors, background); options you set explicitly still win. See Themes.
`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.
`nodePalette`	`string[]`	`undefined`	Ordered fill colors cycled across nodes that do not set their own `color`. Overrides the built-in palette; a `theme` sets this for you.
`draggableNodes`	`boolean`	`false`	Allow nodes to be repositioned by dragging with a pointer (mouse, touch, or pen). Connected flows follow the node live; the manual position holds until the next `render()`/`update()` recomputes the layout.
`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.
`particleFlow`	`boolean`	`false`	Animate particles drifting along each flow ribbon, with density proportional to the ribbon's value. Purely decorative; skipped under `prefers-reduced-motion`.
`edgeGap`	`number`	`0`	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.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Flow direction. `'horizontal'` lays ranks out in columns (flows left→right); `'vertical'` lays them in rows (flows top→bottom).
`axisTitles`	`string[]`	`undefined`	Titles drawn above each column (or beside each row when vertical), one per rank — the axis/dimension labels of an alluvial diagram. Index `i` labels rank `i`. See Alluvial.
`viewPortWidth`	`number`	`800`	Internal SVG viewport width in pixels.
`viewPortHeight`	`number`	`500`	Internal SVG viewport height in pixels.
`highlightConnectedPath`	`boolean`	`true`	Highlight connected flows on interaction. Hovering a node or flow gives a one-hop preview; clicking a node or flow pins an isolate of its full upstream/downstream path (click again, or click another, to change/release).
`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.
`locale`	`{ direction?: 'ltr' \| 'rtl' \| 'auto', messages?: Partial<SankeyMessages> }`	`{ direction: 'ltr' }`	Localization and text-direction. `direction: 'rtl'` mirrors the diagram horizontally (flows read right-to-left) and sets `dir="rtl"` on the container (`'auto'` defers to the document). `messages` overrides the screen-reader strings the diagram generates.

Chord

Set type: 'chord' to draw the radial projection of the same { nodes, edges } model: each node becomes an arc on a ring (its span proportional to total incident flow) and each edge a ribbon crossing the interior. It suits dense many-to-many or symmetric relationships (migration, co-occurrence, adjacency) where a layered Sankey turns into spaghetti. Hovering an arc or ribbon focuses its connections and dims the rest. The arcs' outer corners are rounded by default (arcCornerRadius); set it to 0 for sharp corners.

const sankey = new ApexSankey(el, {type: 'chord'});
sankey.render({
  nodes: [
    {id: 'A', title: 'A'},
    {id: 'B', title: 'B'},
    {id: 'C', title: 'C'},
  ],
  edges: [
    {source: 'A', target: 'B', value: 12, type: 'x'},
    {source: 'B', target: 'C', value: 8, type: 'x'},
    {source: 'C', target: 'A', value: 5, type: 'x'},
  ],
});

Chord mode reuses the tooltip, node/edge click events, and color palette. Sankey-only features (multi-orientation, RTL mirror, animated relayout, node dragging, particle flow) do not apply to it.

Alluvial

An alluvial diagram is the same engine as a Sankey, reached through the same { nodes, edges } model. ApexSankey.buildAlluvialData (also exported as buildAlluvialData) turns categorical records-across-dimensions into that model so you do not hand-build it: it creates one node per (dimension, category) and one edge per adjacent-dimension transition, with each category keeping the same color across every dimension so a cohort reads as one continuous stream. Pair it with axisTitles for the dimension labels.

const input = {
  dimensions: ['2019', '2022', '2025'],
  records: [
    {values: {2019: 'Free', 2022: 'Pro', 2025: 'Pro'}},
    {values: {2019: 'Free', 2022: 'Free', 2025: 'Churned'}},
    {values: {2019: 'Pro', 2022: 'Pro', 2025: 'Team'}, value: 3},
  ],
};

const sankey = new ApexSankey(el, {axisTitles: input.dimensions});
sankey.render({...ApexSankey.buildAlluvialData(input), options: sankey.options});

AlluvialInput fields:

Field	Type	Description
`dimensions`	`string[]`	Ordered dimension (axis) ids, left → right.
`records`	`AlluvialRecord[]`	The subjects flowing across the dimensions.
`palette`	`string[]`	Optional category color palette, cycled per distinct category.

Each AlluvialRecord is { values: Record<string, string>, value?: number } — the category at each dimension (keyed by dimension id), and the weight it contributes (default 1). A record missing a category at some dimension simply skips that adjacency.

Plugins & Events

Subscribe to instance events with on (it returns an unsubscribe function), or package reusable behaviour as a SankeyPlugin and install it with use.

// events
const off = sankey.on('node:click', ({id, node, originalEvent}) => {
  console.log('clicked', id);
});
// ...later
off();

// a reusable plugin: log every clicked node, cleaned up on destroy()
sankey.use({
  name: 'click-logger',
  install: ({chart, on}) => on('node:click', ({id}) => console.log('clicked', id)),
});

Emitted events and their payloads:

Event	Payload	When
`node:click`	`{ id, node, originalEvent }`	A node is clicked.
`node:mouseenter`	`{ id, node, originalEvent }`	The pointer enters a node.
`node:mouseleave`	`{ id, node, originalEvent }`	The pointer leaves a node.
`edge:click`	`{ source, target, value, originalEvent }`	A flow (edge) is clicked.
`edge:mouseenter`	`{ source, target, value, originalEvent }`	The pointer enters a flow.
`edge:mouseleave`	`{ source, target, value, originalEvent }`	The pointer leaves a flow.
`rendered`	none	After the initial render and after each `update()` settles.
`destroyed`	none	On `destroy()`.

A SankeyPlugin is { name, install(ctx) }. install receives { chart, on } and may return a teardown function that runs on destroy(). Every subscription made through ctx.on is also released automatically on destroy().

Built-in plugins

pathTrace ships with the library (importable as pathTrace, or ApexSankey.plugins.pathTrace). Installing it makes a bright pulse cascade along the connected flow path when a node is picked, ribbon by ribbon, cueing the eye to where the flow goes. It is skipped under prefers-reduced-motion and applies to the Sankey projection (not chord).

sankey.use(pathTrace({direction: 'downstream'}));

`PathTraceOptions`	Type	Default	Description
`trigger`	`'click' \| 'hover'`	`'click'`	What starts a trace.
`direction`	`'downstream' \| 'upstream' \| 'both'`	`'downstream'`	Which way flow is traced from the picked node.
`color`	`string`	`'#ffffff'`	Pulse color.
`duration`	`number`	`700`	Milliseconds for a pulse to cross one ribbon.
`stagger`	`number`	`220`	Milliseconds added per hop, so the trace cascades outward.

timePlayback steps the diagram through a sequence of data frames, driven by the chart's own update() so topology-stable frames spring smoothly from one to the next. It ships a small control bar (play/pause + a scrubber). Importable as timePlayback or ApexSankey.plugins.timePlayback.

sankey.render({...frames[0], options: sankey.options});
sankey.use(timePlayback({frames, interval: 1500, loop: true}));

`TimePlaybackOptions`	Type	Default	Description
`frames`	`TimePlaybackFrame[]`	required	Ordered frames (`{ nodes, edges, label? }`). Share topology across frames for a smooth morph.
`interval`	`number`	`1600`	Milliseconds each frame is shown before advancing.
`autoplay`	`boolean`	`false`	Start playing on install.
`loop`	`boolean`	`false`	Loop back to the first frame after the last.
`controls`	`boolean`	`true`	Render the built-in control bar.
`mount`	`HTMLElement`	after the chart	Where to render the control bar.

drillDown turns a large diagram into a set of super-nodes you expand on demand: click a super-node to reveal its constituent flows, click any of its children to collapse it back. The drillable nodes get a pointer cursor so they read as clickable. Expanding animates the children growing out of the super-node (and shrinking back into it on collapse) with their ribbons — driven through the chart's own update() (which accepts an optional SankeyTransition hint for this). It is built on the pure ApexSankey.collapseGroups transform (also exported as collapseGroups), which re-routes and merges the flows of a collapsed group. Importable as drillDown or ApexSankey.plugins.drillDown; applies to the Sankey projection (not chord). Seed the initial collapsed render with ApexSankey.collapseGroups so there is no load-time morph.

const detail = {nodes, edges};
const groups = [{id: 'Fossil', title: 'Fossil', children: ['Coal', 'Gas', 'Oil']}];
sankey.render({...ApexSankey.collapseGroups(detail, groups, ['Fossil']), options: sankey.options});
sankey.use(drillDown({...detail, groups}));

`DrillDownOptions`	Type	Default	Description
`nodes`	`SankeyGraphNode[]`	required	The full, detailed leaf nodes before any collapsing.
`edges`	`SankeyGraphEdge[]`	required	The full, detailed flows between the leaf nodes.
`groups`	`DrillDownGroup[]`	required	Group definitions (`{ id, title, color?, children }`); each collapses its children into one super-node.
`expanded`	`string[]`	`[]`	Group ids expanded on install; every other group starts collapsed.

Comparison split-view

ApexSankey.compare(element, config) renders two diagrams of the same flow model side by side — a "before" and an "after". It outlines each flow by how it changed between them (added, removed, or changed, from the pure diffGraphs transform, also exported), draws a legend, and links the panels so hovering a node or flow highlights its twin in the other. It is built on the public surface only (two ordinary ApexSankey instances plus their node:* and edge:* events) and returns a SankeyComparison handle exposing before, after, the computed diff, and destroy().

const cmp = ApexSankey.compare(el, {
  before: {nodes, edges: edges2024, title: '2024'},
  after: {nodes, edges: edges2025, title: '2025'},
});
// later: cmp.destroy();

`ComparisonConfig`	Type	Default	Description
`before`	`{ nodes, edges, title? }`	required	The left panel's flow graph and optional heading.
`after`	`{ nodes, edges, title? }`	required	The right panel's flow graph and optional heading.
`options`	`Partial<SankeyOptions>`	`{}`	Base options shared by both panels (each manages its own width).
`syncHighlight`	`boolean`	`true`	Highlight the twin node or flow in the other panel on hover (a cursor lands on a ribbon at least as readily as on a node).
`showDiff`	`boolean`	`true`	Outline added / removed / changed flows in each panel.
`showLegend`	`boolean`	`true`	Render the diff color legend below the panels.
`diffColors`	`{ added?, removed?, changed? }`	greens/reds/ambers	Override the diff outline colors.

Themes

Pass theme to seed a coordinated set of visual defaults in one shot. Built-in themes: 'light' (the default look), 'dark', 'midnight', 'mint', and 'sunset'. A theme sits between the built-in defaults and your explicit options, so anything you set yourself still wins.

const sankey = new ApexSankey(el, {theme: 'dark'});

Register a brand preset once, then reference it by name:

ApexSankey.registerTheme('acme', {
  nodePalette: ['#ff5a5f', '#087f8c', '#5d2e8c'],
  fontColor: '#1a1a1a',
  canvasStyle: 'background: #faf7f2; box-sizing: border-box;',
});
const sankey = new ApexSankey(el, {theme: 'acme'});

You can also pass an inline SankeyTheme object directly as theme. A SankeyTheme may set any subset of the following (each maps to the option of the same name; omitted fields keep their default):

`SankeyTheme` field	Type	Description
`nodePalette`	`string[]`	Ordered node fill colors, cycled across nodes without their own `color`.
`fontColor`	`string`	CSS color for node labels.
`edgeOpacity`	`number`	Opacity of the flow ribbons (0–1).
`edgeGradientFill`	`boolean`	Fill ribbons with a source→target gradient.
`nodeBorderColor`	`string \| null`	CSS color for the node border (`null` disables).
`canvasStyle`	`string`	CSS on the SVG root container, typically the background and border.
`tooltipTheme`	`'light' \| 'dark'`	Tooltip color preset.

Localization & RTL

The diagram's screen-reader strings live in SankeyMessages; pass a Partial<SankeyMessages> via locale.messages to translate any subset (unset keys keep their English defaults, exported as DEFAULT_SANKEY_MESSAGES). Visible tooltips are localized separately via tooltipTemplate / nodeTooltipTemplate.

`SankeyMessages` key	Type	Description
`diagramLabel`	`(ctx: SankeyDiagramLabelContext) => string`	SVG root aria-label summary (node/flow counts + largest flow).
`nodeAriaLabel`	`(ctx: SankeyNodeLabelContext) => string`	Per-node aria-label (incoming/outgoing flow summary).
`edgeAriaLabel`	`(ctx: SankeyEdgeLabelContext) => string`	Per-edge aria-label. Default: `Flow from {source} to {target}: {value} units`.
`nodesGroupLabel`	`string`	aria-label for the `<g>` wrapping all nodes. Default: `'Sankey nodes'`.

const sankey = new ApexSankey(el, {
  locale: {
    direction: 'rtl',
    messages: {nodesGroupLabel: 'العقد'},
  },
});

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

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

Family theme tokens (`--apx-*`)

Every chart in the ApexCharts family reads the same five root tokens, so a page can state its brand once and have trees, flow diagrams, Gantt charts and plots all follow:

Token	Role
`--apx-accent`	The colour that means interactive or selected
`--apx-fore`	Text and anything that must stay legible on the surface
`--apx-grid`	Hairlines: borders, gridlines, connectors
`--apx-surface`	The plane content sits on
`--apx-series-1` … `--apx-series-N`	An ordered categorical palette (1-based, stops at the first gap)

:root {
  --apx-accent: #5b21b6;
  --apx-fore: #101828;
  --apx-grid: #e4e7ec;
  --apx-surface: #ffffff;
}

@media (prefers-color-scheme: dark) {
  :root {
    --apx-fore: #f8fafc;
    --apx-grid: #334155;
    --apx-surface: #0f172a;
  }
}

Custom properties inherit, so declaring them on :root reaches every chart on the page. They resolve below anything you configured explicitly, so adopting them cannot change a chart that was already themed:

product CSS variable  >  explicit option  >  --apx-* token  >  built-in default

An option set to a value equal to its built-in default is indistinguishable from one left alone, and the token wins there. Set a product variable if you need a value pinned regardless.

Named themes

registerTheme from @apex/commons records a named set of tokens on a registry shared by the whole family, so a brand theme registered once from any product is resolvable by name from all of them:

import {registerTheme} from '@apex/commons';

registerTheme('acme', {
  tokens: {accent: '#5b21b6', fore: '#101828', grid: '#e4e7ec', surface: '#ffffff'},
});

A named theme's tokens sit one layer below the CSS --apx-* tokens, so the cascade still wins over the registry.

Reference it through the theme option, alongside the Sankey-specific named themes described in Themes. The two registries are complementary: a Sankey theme carries diagram-specific defaults (palette, edge opacity, canvas style), while a family theme carries the cross-product token roles.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
demo		demo
LICENSE		LICENSE
README.md		README.md
apexsankey.d.ts		apexsankey.d.ts
apexsankey.es.min.js		apexsankey.es.min.js
apexsankey.min.js		apexsankey.min.js
package.json		package.json

Navigation Menu

Uh oh!

Repository files navigation

ApexSankey

Dependency

Installation

Usage

Setting the License

Methods

ApexSankey Options

Chord

Alluvial

Plugins & Events

Built-in plugins

Comparison split-view

Themes

Localization & RTL

Expected data format

Family theme tokens (`--apx-*`)

Named themes

About

Releases

Packages

Used by

Contributors

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

ApexSankey

Dependency

Installation

Usage

Setting the License

Methods

ApexSankey Options

Chord

Alluvial

Plugins & Events

Built-in plugins

Comparison split-view

Themes

Localization & RTL

Expected data format

Family theme tokens (--apx-*)

Named themes

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Family theme tokens (`--apx-*`)