Methods

An ApexSankey instance is created with new ApexSankey(element, options) and drawn with render(data). The render() call returns the internal graph renderer, which exposes methods for re-rendering and export.

Constructor

import { ApexSankey } from 'apexsankey'

const container = document.getElementById('chart')
const sankey = new ApexSankey(container, {
  width: 800,
  height: 500,
  nodeWidth: 20,
})

The constructor applies dimensions to the host element immediately but does not draw anything. Call render() to build the SVG.

Parameter	Type	Description
`element`	`HTMLElement`	Container element for the diagram SVG
`options`	`Partial<SankeyOptions>`	Configuration; any omitted field falls back to its default

render(data)

Builds the Sankey diagram inside the container. Returns the internal SankeyGraphRenderer instance.

const graph = sankey.render({
  nodes: [
    { id: 'a', title: 'Source A' },
    { id: 'b', title: 'Target B' },
  ],
  edges: [
    { source: 'a', target: 'b', value: 42, type: 'flow' },
  ],
})

`data` field	Type	Description
`nodes`	`SankeyGraphNode[]`	Entities: `{ id, title, color? }`
`edges`	`SankeyGraphEdge[]`	Flows: `{ source, target, value, type }`. `value` sets band width
`options`	`object`	Optional data-level layout options (see Node and Link Ordering)

render() throws if the container element is not found.

update(data, transition?)

Transition an already-rendered instance to a new dataset. Returns the graph renderer.

const sankey = new ApexSankey(el, options)
sankey.render({ nodes, edges: edges2024, options: sankey.options })

// later, on the same instance:
sankey.update({ nodes, edges: edges2025, options: sankey.options })

When the new data shares the current topology (the same nodes and flows, only different values or positions), nodes and ribbons spring to their new places. When the topology differs, the diagram morphs through the change: entering flows unfurl out of their source node, survivors slide, and removed flows retract and dissolve.

It redraws instantly instead when animation is disabled or the user prefers reduced motion. The output at rest is identical to render() either way.

See Data Updates and Morphing.

graph.render(options)

Re-draw the diagram using the renderer returned by render(data). Pass keepOldPosition: true to preserve the current node layout across a re-render instead of recomputing positions from scratch.

const graph = sankey.render(data)

// later — re-render without recomputing the layout
graph.render({ keepOldPosition: true })

Option	Type	Default	Description
`keepOldPosition`	`boolean`	`false`	Keep the existing node positions instead of recomputing the layout

graph.exportToSvg()

Export the current diagram as an SVG file. Triggers a browser download.

const graph = sankey.render(data)

document.getElementById('export-btn').addEventListener('click', () => {
  graph.exportToSvg()
})

The built-in toolbar already includes an export button when enableToolbar is true (the default). Use exportToSvg() directly only when you need a custom export trigger. See the Export guide for details.

graph.getMessages()

Returns the resolved, localized screen-reader strings for this diagram (English defaults merged with locale.messages).

const graph = sankey.render(data)

const messages = graph.getMessages()

on(event, handler)

Subscribe to an instance event. Returns an unsubscribe function.

const off = sankey.on('node:click', ({ id }) => console.log(id))

// later
off()

Event	Payload
`node:click`	`SankeyNodeEventArgs`
`node:mouseenter`	`SankeyNodeEventArgs`
`node:mouseleave`	`SankeyNodeEventArgs`
`edge:click`	`SankeyEdgeEventArgs`
`edge:mouseenter`	`SankeyEdgeEventArgs`
`edge:mouseleave`	`SankeyEdgeEventArgs`
`rendered`	none; fires after the initial render and after each `update()` settles
`destroyed`	none

The event names and payloads are typed, so sankey.on('node:click', ...) narrows its handler argument in TypeScript.

off(event, handler)

Remove a handler previously registered with on. Equivalent to calling the function on returned.

const onClick = ({ id }) => console.log(id)

sankey.on('node:click', onClick)
sankey.off('node:click', onClick)

use(plugin)

Install a plugin. Its install runs immediately with a plugin context, and any teardown it returns runs on destroy(). Returns the instance, so calls chain.

import { ApexSankey, pathTrace, timePlayback } from 'apexsankey'

sankey
  .use(pathTrace({ trigger: 'hover', direction: 'both' }))
  .use(timePlayback({ frames, interval: 1200, loop: true }))

The three built-in plugins are also reachable as ApexSankey.plugins.pathTrace, ApexSankey.plugins.timePlayback and ApexSankey.plugins.drillDown. See Plugins and Events.

ApexSankey.registerTheme(name, theme)

Static method. Register (or override) a named theme, then reference it by name through the theme option. Use it for brand presets shared across an app.

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

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

See Themes.

ApexSankey.buildAlluvialData(input)

Static method. Build the { nodes, edges } for an alluvial diagram from categorical records across dimensions. Pair it with the axisTitles option for the dimension labels.

const data = ApexSankey.buildAlluvialData({
  dimensions: ['2019', '2022'],
  records: [{ values: { '2019': 'Free', '2022': 'Pro' } }],
})

new ApexSankey(el, { axisTitles: ['2019', '2022'] })
  .render({ ...data, options })

Also available as the named export buildAlluvialData. See Alluvial Diagrams.

ApexSankey.collapseGroups(data, groups, collapsed)

Static method. Project a detailed graph to an aggregated one by collapsing the given groups: every id in collapsed becomes a single super-node whose flows are re-routed and merged. This is the pure transform behind the drillDown plugin, exposed so you can seed an initially-collapsed render.

const detail = { nodes, edges }
const groups = [{ id: 'Fossil', title: 'Fossil', children: ['Coal', 'Gas'] }]

sankey.render({
  ...ApexSankey.collapseGroups(detail, groups, ['Fossil']),
  options,
})

Also available as the named export collapseGroups.

ApexSankey.compare(element, config)

Static method. Render a before/after comparison of two diagrams into one host element: two linked instances that outline each flow by how it changed and highlight the same node across both panels on hover.

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

// later
cmp.destroy()

Returns a SankeyComparison handle exposing before, after, diff and destroy(). See Comparison Split-view.

destroy()

Destroys the chart instance and cleans up its DOM and internal resources.

sankey.destroy()

destroy() runs every installed plugin's teardown, emits destroyed, drops all event handlers, then releases the chart context (which removes the tooltip element). It is idempotent, so a second call is a no-op.

Call it before removing the container from the DOM, or in a framework component's unmount/cleanup phase, to avoid leaking listeners.

getInstanceId()

Returns the unique identifier for this chart instance.

const id = sankey.getInstanceId()

ApexSankey.setLicense(key)

Static method. Sets the global ApexCharts license key. Call it once at app startup, before creating any chart instance. Without a valid license the chart renders with a watermark.

import { ApexSankey } from 'apexsankey'

ApexSankey.setLicense('YOUR_LICENSE_KEY')

See Setting the License for framework-specific patterns.

Re-rendering with new data

Prefer update(data) for a dataset change on a live instance: it animates the transition and falls back to an instant redraw when it cannot.

const sankey = new ApexSankey(el, options)
sankey.render(initialData)

async function reload() {
  const data = await fetchLatest()
  sankey.update(data)      // springs or morphs into the new data
}

render(data) still works and rebuilds from scratch, which is what you want for the first render or after swapping the container. graph.render({ keepOldPosition: true }) remains available for a re-render that keeps the existing node positions.

Framework wrappers

In React, the ApexSankey component exposes the graph renderer through a ref:

import { useRef } from 'react'
import { ApexSankey } from 'react-apexsankey'
import type { ApexSankeyRef } from 'react-apexsankey'

export default function Diagram() {
  const ref = useRef<ApexSankeyRef>(null)

  return (
    <div>
      <button onClick={() => ref.current?.graph?.render({ keepOldPosition: true })}>
        Re-render
      </button>
      <ApexSankey ref={ref} data={data} options={options} />
    </div>
  )
}

The React and Vue wrappers call destroy() automatically on unmount, so you do not need to manage cleanup manually.