React ApexSankey

Installation

npm install react-apexsankey apexsankey @svgdotjs/svg.js

Or with yarn:

yarn add react-apexsankey apexsankey @svgdotjs/svg.js

Demo

View Demo Project created using react-apexsankey

Loading ApexSankey

Important: You must load ApexSankey before using the React component. Choose one of the following methods:

Option 1: ES Module Import (Recommended)

Import ApexSankey at your app's entry point to register it globally:

// main.tsx or index.tsx
import "apexsankey";
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Option 2: CDN Script Tags

Add the scripts to your index.html before your app bundle:

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/@svgdotjs/svg.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/apexsankey/apexsankey.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Quick Start

import ApexSankey from "react-apexsankey";

const data = {
  nodes: [
    { id: "oil", title: "Oil" },
    { id: "gas", title: "Natural Gas" },
    { id: "coal", title: "Coal" },
    { id: "fossil", title: "Fossil Fuels" },
    { id: "energy", title: "Energy" },
  ],
  edges: [
    { source: "oil", target: "fossil", value: 15 },
    { source: "gas", target: "fossil", value: 20 },
    { source: "coal", target: "fossil", value: 25 },
    { source: "fossil", target: "energy", value: 60 },
  ],
};

function App() {
  return (
    <ApexSankey
      data={data}
      options={{
        width: 800,
        height: 600,
        nodeWidth: 20,
      }}
    />
  );
}

License Setup

If you have a commercial license, set it once at app initialization before rendering any charts:

import { setApexSankeyLicense } from "react-apexsankey";

// call this at the top of your app
setApexSankeyLicense("your-license-key-here");

Example with React app entry point:

// main.tsx or index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { setApexSankeyLicense } from "react-apexsankey";
import App from "./App";

// set license before rendering
setApexSankeyLicense("your-license-key-here");

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Using Refs

Access the underlying SankeyGraph instance via refs:

import { useRef, useEffect } from "react";
import ApexSankey, { ApexSankeyRef } from "react-apexsankey";

function App() {
  const chartRef = useRef<ApexSankeyRef>(null);

  useEffect(() => {
    if (chartRef.current?.graph) {
      console.log("Graph instance:", chartRef.current.graph);
      console.log("Max rank:", chartRef.current.graph.maxRank);
    }
  }, []);

  return <ApexSankey ref={chartRef} data={data} options={options} />;
}

The ref handle is { graph, refreshTokens }. refreshTokens() repaints the diagram with the current theme; see Theming and Ignite UI.

Props

PropTypeRequiredDescription
dataGraphDataYesSankey diagram data (nodes and edges)
optionsNoConfiguration options for the diagram
classNamestringNoCSS class name for the container element
styleCSSPropertiesNoInline styles for the container element

Data Format

Nodes

interface Node {
  id: string; // unique identifier
  title: string; // display label
  color?: string; // optional custom color
}

Edges

interface Edge {
  source: string; // source node id
  target: string; // target node id
  value: number; // edge weight/size
  type?: string; // tells parallel edges between the same two nodes apart
  color?: string; // optional custom color
}

Complete Data Structure

interface GraphData {
  nodes: Node[];
  edges: Edge[];
  options?: {
    order?: string[][][]; // custom node ordering
    alignLinkTypes?: boolean; // align links by type
  };
}

Options

OptionTypeDefaultDescription
widthnumber | string'100%'Width of graph container
heightnumber | string'auto'Height of graph container
canvasStylestring"border: 1px solid #caced0; box-sizing: border-box"CSS styles for canvas root container
spacingnumber20Spacing from top and left of graph container
nodeWidthnumber20Width of graph nodes
nodeBorderWidthnumber1Border width of nodes in pixels
nodeBorderColorstringnullBorder color of nodes
onNodeClickundefinedCallback function for node click
edgeOpacitynumber0.4Opacity value for edges (0 to 1)
edgeGradientFillbooleantrueEnable gradient fill based on node colors
enableTooltipbooleantrueEnable tooltip on hover
enableToolbarbooleantrueEnable/disable graph toolbar
tooltipIdstring"apexsankey-tooltip-container"Tooltip HTML element id
tooltipTemplate(content) => stringdefault templateHTML template for tooltip
tooltipBorderColorstring"#E2E8F0"Border color of tooltip
tooltipBGColorstring"#FFFFFF"Background color of tooltip
fontSizestring"14px"Font size of node labels
fontFamilystring""Font family of node labels
fontWeightstring"400"Font weight of node labels
fontColorstring"#212121"Font color of node labels
themestring | object-A built-in theme (light, dark, midnight, mint, sunset), a name registered with ApexSankey.registerTheme, or an inline theme object. Options, the diagram's CSS variables and the family tokens beat it
tokensbooleantruefalse stops the diagram reading the family tokens and the Ignite UI theme (apexsankey 1.14.0 or later)
designSystembooleantruefalse stops the diagram reading the Ignite UI theme; has an effect only with the apexsankey/ignite-ui add-on loaded (apexsankey 1.14.0 or later)

Node order

ApexSankey places nodes into columns and orders each column to cut edge crossings. There is no option to pin the order: an order array in the data or options has no effect, and since 1.12.4 the unused code behind it is gone, so you can delete one if you pass it. To let readers move nodes themselves, set draggableNodes: true. See Node ordering for what you can adjust.

Custom Tooltip

const options = {
  enableTooltip: true,
  tooltipTemplate: ({ source, target, value }) => `
    <div style="padding: 8px;">
      <strong>${source.title}</strong> → <strong>${target.title}</strong>
      <br />
      Value: ${value}
    </div>
  `,
};

Styling

Container Styling

<ApexSankey
  data={data}
  className="my-sankey-chart"
  style={{ border: "1px solid #ccc", borderRadius: 8 }}
  options={options}
/>

Canvas Styling

const options = {
  canvasStyle: "background: #f6f6f6; border: 1px solid #caced0;",
};

Theming and Ignite UI

From react-apexsankey 1.1.0, options types theme, tokens and designSystem. Themes, the --apex-sankey-* CSS variables and the --apx-* tokens work as in the core library; an option you pass beats the variables and tokens, so leave out any option a stylesheet should drive. See Themes.

To follow an Ignite UI theme on the page, import the add-on once, anywhere in your app, before the first diagram renders. It ships in the core apexsankey package (1.14.0 or later) and needs no extra licence key:

import "apexsankey/ignite-ui";

// per diagram: designSystem: false ignores the Ignite UI theme, tokens: false ignores every token.
// Declare the options at module scope so a re-render does not rebuild the diagram.
const noIgnite = { designSystem: false };

<ApexSankey data={data} options={noIgnite} />

The diagram reads its theme whenever it renders, including when data or options change. When the theme changes without a prop change, for example after a stylesheet swap for an Ignite UI light/dark switch, a class toggle that sets the variables, or the add-on loading after the first render, call refreshTokens() on the ref. Nodes stay where they are, dragged ones included, and the view does not move:

const chartRef = useRef<ApexSankeyRef>(null);

themeLink.onload = () => chartRef.current?.refreshTokens();

<ApexSankey ref={chartRef} data={data} />

refreshTokens() needs apexsankey 1.14.0; on an older core and before the first render it does nothing. See Using with Ignite UI.

TypeScript

All types are exported for use in your TypeScript projects:

import ApexSankey, {
  GraphData,
  Node,
  Edge,
  SankeyOptions,
  ApexSankeyRef,
  ApexSankeyProps,
} from "react-apexsankey";

SSR Support

This component is SSR-safe and renders an empty container on the server. The chart is only rendered client-side after hydration.