Using with Ignite UI

From ApexSankey 1.14.0, diagrams can follow an Ignite UI theme loaded on the page. One import turns it on: the node palette, label text, the keyboard focus ring, the tooltip, the font, and a dark tooltip under a dark theme then come from the theme's --ig-* tokens. The add-on needs no extra licence key and ranks below every style you set, so a diagram you already themed stays as it is.

Opt in

With a bundler

Import the add-on once, before the first render():

import ApexSankey from 'apexsankey'
import 'apexsankey/ignite-ui'

With script tags

Load apexsankey.ignite-ui.min.js, before or after apexsankey.min.js:

<script src="https://cdn.jsdelivr.net/npm/apexsankey@1.14.0/apexsankey.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/apexsankey@1.14.0/apexsankey.ignite-ui.min.js"></script>

Load it before the first render. A diagram rendered earlier picks it up on its next render() or refreshTokens(). Without the add-on the --ig-* tokens are ignored, with no error; the --apx-* tokens work either way.

What follows the theme

Diagram part	Ignite UI token
Node palette	The theme's color families: --ig-primary-seed, --ig-secondary-seed, then info, success, warn and error; the built-in palette fills any row the theme does not declare
Label text	--ig-gray-800
fontFamily	--ig-font-family
Keyboard focus ring	--ig-primary-seed
Tooltip border	--ig-gray-300
Tooltip surface and text	--ig-surface-overlay and its contrast color (Ignite UI 7.5 and later)
Light or dark tooltip	--ig-theme-variant

• When the theme declares a dark variant and nothing set tooltipTheme, the tooltip renders dark.
• Tooltip colors from the theme apply only while the tooltip theme matches the variant.
• A node's own color always stays.

Ranking

Every color and the font resolve in one order, highest first. Ignite UI fills only what nothing above it set.

Rank	Source	Example
1	An option you pass	nodePalette, fontColor, fontFamily, a node's color
2	The diagram's own CSS variables	--apex-sankey-focus-color and the other --apex-sankey-* variables
3	The family --apx-* tokens	--apx-accent, --apx-fore, --apx-grid, --apx-font-family
4	A named theme	One of the built-in themes, a preset from registerTheme, or the dark tooltip preset (tooltipTheme: 'dark')
5	Ignite UI	The --ig-* tokens, with the add-on loaded
6	Built-in defaults	The default palette and light tooltip

See Themes for the named themes, the --apex-sankey-* variables and the --apx-* tokens.

Turn it off

The add-on applies to every diagram on the page. Per diagram, two top-level options:

const sankey = new ApexSankey(el, {
  designSystem: false, // ignore the Ignite UI theme, keep the --apx-* tokens
  // tokens: false,    // ignore every token: --apx-* and Ignite UI
})

Both default to true. Without the add-on, designSystem does nothing.

Switching themes at runtime

The diagram reads its theme on every render, and update() takes only data. When the page swaps its Ignite UI stylesheet, for example from the light to the dark variant, call refreshTokens():

const link = document.getElementById('ig-theme')
link.addEventListener('load', () => sankey.refreshTokens(), { once: true })
link.href = '/themes/material-dark.css'

refreshTokens() re-reads the --apex-sankey-* variables, the --apx-* tokens, the named or registered theme and the Ignite UI theme, and repaints: node colors follow the palette as it resolves now, and so do the labels, the tooltip, the focus ring and the particles. Nodes stay where they are, dragged ones included, and the view does not move. Call it as well when the add-on loads after the first render.

Web fonts

An Ignite UI theme names its font in --ig-font-family but does not load it, so add the font to the page yourself (a link to the font service or your own @font-face). The diagram writes the font name into its text and does not measure it, so the browser swaps the font in when it arrives, with nothing to call.

Other Apex products on the page

The add-on registers the Ignite UI adapter the Apex products share, so ApexTree, ApexGantt and ApexMaps on the same page follow the theme too (maps take the basemap and no-data greys only from their own add-on). With several of them, load the add-on from the newest package. ApexCharts charts take their own add-on, apexcharts/features/ignite-ui; see Using ApexCharts with Ignite UI. That one themes diagrams as well, but from a script tag only once apexcharts.js has loaded, so on a script-tag page load apexsankey.ignite-ui.min.js for the diagrams.

Frequently asked questions

Does the add-on need a licence key?

No. It falls under the diagram's own licence, which is unchanged, and has no premium tier.

Do I need Ignite UI installed to use ApexSankey?

No. The add-on only reads the --ig-* custom properties an Ignite UI theme declares on the page; with no such theme it changes nothing.