Themes
A theme seeds a coordinated set of visual defaults in one option, so a diagram does not need eight colors set by hand to look deliberate.
Built-in themes
const sankey = new ApexSankey(document.getElementById('chart'), {
theme: 'midnight',
})
sankey.render(data)
| Theme | Appearance |
|---|---|
'light' | The default light look |
'dark' | Dark canvas, light labels |
'midnight' | Deep blue canvas with a cool palette |
'mint' | Light canvas with a green-leaning palette |
'sunset' | Warm palette on a soft background |
What a theme sets
A theme is a bundle of the ordinary options:
| Field | Type | Description |
|---|---|---|
nodePalette | string[] | Ordered node fill colors, cycled across nodes without their own color |
fontColor | string | Node label color |
edgeOpacity | number | Ribbon opacity, 0 to 1 |
edgeGradientFill | boolean | Fill ribbons with a source-to-target gradient |
nodeBorderColor | string | null | Node border color; null disables it |
canvasStyle | string | CSS on the SVG root, typically background and border |
tooltipTheme | 'dark' | 'light' | Tooltip color preset |
Precedence
Options you set explicitly always win over the theme. From 1.14.0 the --apex-sankey-* CSS variables and the --apx-* family tokens beat it too (see CSS variables). That makes a theme a baseline rather than a straitjacket:
const sankey = new ApexSankey(el, {
theme: 'sunset', // seeds palette, canvas, label color
edgeOpacity: 0.6, // but this specific value wins
})
Inline themes
theme also accepts an object directly, which is convenient for a one-off:
const sankey = new ApexSankey(el, {
theme: {
nodePalette: ['#0ea5e9', '#6366f1', '#a855f7'],
fontColor: '#0f172a',
edgeOpacity: 0.45,
canvasStyle: 'background: #f8fafc; box-sizing: border-box;',
tooltipTheme: 'light',
},
})
Brand presets
For a theme reused across an app, register it once by name and reference it everywhere. This keeps the palette in one place instead of copied into every chart:
import { ApexSankey } from 'apexsankey'
ApexSankey.registerTheme('acme', {
nodePalette: ['#ff5a5f', '#087f8c', '#5d2e8c'],
fontColor: '#1a1a1a',
canvasStyle: 'background: #faf7f2; box-sizing: border-box;',
})
// anywhere afterwards
new ApexSankey(el, { theme: 'acme' }).render(data)
Register before constructing any instance that names the theme. Registering an existing name overrides it, which is how you would re-theme a whole app at runtime.
Palette only
If all you want is a different set of node colors, skip themes and set nodePalette:
const sankey = new ApexSankey(el, {
nodePalette: ['#2563eb', '#16a34a', '#f59e0b', '#dc2626'],
})
The palette cycles across nodes in order. A node that sets its own color in the data keeps it and is skipped in the cycle. See Node and Edge Styling.
CSS variables
Themes cover the SVG's own paint. For anything you would rather drive from a stylesheet, the diagram also reads CSS custom properties from its container or any ancestor. That path is useful when the colors already live in a design system, or when they need to respond to a prefers-color-scheme media query.
| Variable | Sets |
|---|---|
--apex-sankey-label-color | fontColor |
--apex-sankey-label-font-size | fontSize |
--apex-sankey-font-family | fontFamily |
--apex-sankey-node-width | nodeWidth (the drawn node rectangle only, see below) |
--apex-sankey-node-border-color | nodeBorderColor |
--apex-sankey-node-border-width | nodeBorderWidth |
--apex-sankey-edge-opacity | edgeOpacity |
--apex-sankey-edge-gradient | edgeGradientFill (true or false) |
--apex-sankey-tooltip-bg | tooltipBGColor |
--apex-sankey-tooltip-border-color | tooltipBorderColor |
--apex-sankey-tooltip-font-color | tooltipFontColor |
--apex-sankey-tooltip-theme | tooltipTheme (light or dark) |
--apex-sankey-focus-color | The keyboard focus ring (default #005FCC). From 1.14.0 |
--apex-sankey-particle-color | The particle flow particles (default rgba(255,255,255,0.9)). From 1.14.0 |
--apex-sankey-node-width sets how wide each node is drawn, but the layout still spaces columns and attaches ribbons by the nodeWidth option (default 20), so a different value leaves a gap or an overlap between a node and its ribbons. Keep the two equal, or set nodeWidth alone.
Precedence. From 1.14.0 every styling option resolves in one order, highest first:
- An option you pass. It counts as passed when it is in the options you gave the constructor, even at its default value.
- The
--apex-sankey-*variable. - The family
--apx-*token for that role (see below). - A named theme: a built-in or registered Sankey theme, the dark tooltip preset (
tooltipTheme: 'dark', which'dark'and'midnight'set), or a family theme registered under the same name. - An Ignite UI theme, with the Ignite UI add-on loaded.
- The built-in default.
Before 1.14.0 a variable beat an option you passed. Now the option wins, so drop the option from your config if a variable should drive it.
The diagram reads the variables and tokens when it renders, and update() takes only data. After a change without a render (a class toggle, a stylesheet swap, an OS light or dark flip picked up by a media query), call refreshTokens(). 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:
document.body.classList.toggle('dark')
sankey.refreshTokens()
// follow the OS setting when your variables sit in a prefers-color-scheme query
matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => sankey.refreshTokens())
See Methods.
Family root tokens
Declare the --apx-* tokens once on :root and the ApexCharts-family products on the page pick them up: charts, sankey diagrams, trees and gantt charts. From 1.14.0 a diagram reads these:
| Token | What it sets in a diagram |
|---|---|
--apx-series-1 … --apx-series-N | The node palette, for nodes and chord arcs without their own color; ribbons take their colors from the nodes |
--apx-fore | Label text (fontColor) and tooltip text |
--apx-grid | Node border (nodeBorderColor) and tooltip border |
--apx-surface | Tooltip background |
--apx-font-family | fontFamily |
--apx-accent | The keyboard focus ring, only while an Ignite UI theme is on the page with the add-on loaded |
The canvas background still comes from the canvasStyle option.
:root {
--apx-accent: #4f46e5; /* primary accent */
--apx-fore: #1f2937; /* label and tooltip text */
--apx-grid: #e5e7eb; /* node and tooltip borders */
--apx-surface: #ffffff; /* tooltip background */
/* ordered palette: the node colors */
--apx-series-1: #4f46e5;
--apx-series-2: #06b6d4;
}
Like the --apex-sankey-* variables, the tokens are read when the diagram renders; call refreshTokens() after a change without a render.
They resolve below anything the diagram sets for itself, and above a named theme. A diagram already styled through its own options, or through the --apex-sankey-* variables, is untouched, while the tokens beat a built-in or registered theme per key: with only --apx-grid declared, the node border takes the token while the label color keeps the theme's. The --apx-series-N palette replaces a theme's nodePalette as a whole, and a nodePalette you pass beats it. Set tokens: false to stop one diagram reading the --apx-* tokens.
The point is that these are not this library's variables. They are the family's, so a design system declares its palette once rather than once per product.
From ApexSankey 1.14.0, an Ignite UI theme on the page can supply the node palette, labels, font and tooltip too, through an add-on that needs no extra licence key, one rank below a named theme. See Using with Ignite UI.