Home > Docs > Using with Ignite UI

Using with Ignite UI

From ApexCharts 8.8.0, charts can follow an Ignite UI theme loaded on the page. One import turns it on: the series colors, text, gridlines, tooltips and menus, the font, and light or dark then come from the theme's --ig-* tokens, with no chart options. The add-on needs no extra key, because the licence you already use for ApexCharts covers it, and it ranks below every color source you control, so a chart you already themed stays as it is.

Key takeaways

Opt in with one import: import 'apexcharts/features/ignite-ui', or dist/features/ignite-ui.js after apexcharts.js on a script-tag page. Without it the --ig-* tokens are ignored, with no error.
Lowest rank above the defaults: explicit options, the chart's own CSS, --apx-* tokens, a named theme and an explicit palette all win over Ignite UI.
Turn it off per chart: theme.designSystem: false keeps the --apx-* tokens; theme.tokens: false turns off both.
After a stylesheet swap, call chart.refreshTokens().
No extra licence key: your ApexCharts licence covers it, and there is no premium tier.

Opt in

With a bundler

Import the add-on once, anywhere before the first chart renders:

import ApexCharts from 'apexcharts'
import 'apexcharts/features/ignite-ui'

It works with a tree-shaken build too, next to apexcharts/core. It is not part of any default bundle, the full one included, so pages that do not use Ignite UI pay nothing for it.

With script tags

Load dist/features/ignite-ui.js after apexcharts.js:

<script src="https://cdn.jsdelivr.net/npm/apexcharts@8.8.1/dist/apexcharts.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/apexcharts@8.8.1/dist/features/ignite-ui.js"></script>

Load it before the first render. A chart rendered earlier picks it up on its next update, resize or refreshTokens().

The add-on brings a small stylesheet, apexcharts-ignite-ui.css, which the chart injects right after its main stylesheet. With chart.injectStyleSheet: false, link dist/apexcharts-ignite-ui.css yourself, after apexcharts.css. Inside a shadow root the chart always injects both.

What follows the theme

Chart part	Ignite UI token
Series 1 to 6	`--ig-primary-seed`, then the secondary, info, success, warn and error seeds (each else its `-500`)
Series 7 to 12, then 13 to 18	The same six at `-300`, then at `-700`
Text, muted text, gridlines and borders	`--ig-gray-800`, `--ig-gray-600`, `--ig-gray-300`
`chart.fontFamily`	`--ig-font-family`
Tooltips, axis tooltips, the export and context menus	The theme's gray steps, and `--ig-surface-overlay` from Ignite UI 7.5
Light or dark	`--ig-theme-variant`

The built-in palette fills any series row the theme does not declare.
Text and line colors apply only while the chart's mode matches the theme's variant, so a dark theme's light grays never land on a light chart. Series colors apply in either mode.
With theme.mode unset, a dark Ignite UI theme makes the chart dark. A mode you pass, a named theme's mode and theme.follow: 'os' all win, and a light theme changes nothing about the mode.
A chart made dark this way keeps a transparent background, so the page's surface shows through. chart.background and --apx-surface still paint one. A PNG or SVG export of such a chart is drawn on the theme's surface color, else #343A3F.
theme.accessibility.colorBlindMode and theme.monochrome keep their own colors.
On an Ignite UI 7.4 dark theme the context menu keeps its light look: the overlay tokens arrive in 7.5.

Ranking

Every color, the font and the mode resolve in one order, highest first. A higher source wins wherever it sets a value; Ignite UI fills only what nothing above it set.

Rank	Source	Example
1	An option you pass	`colors`, `chart.foreColor`, `chart.fontFamily`, `grid.borderColor`, `theme.mode`
2	The chart's own CSS	Your rules for the tooltip and menus; the Ignite UI rules add no specificity, so a page rule always wins
3	The family `--apx-*` tokens	`--apx-accent`, `--apx-fore`, `--apx-grid`, `--apx-series-1`, `--apx-font-family`
4	A named theme or palette	`theme.name` from `ApexCharts.registerTheme()`, `theme.palette`
5	Ignite UI	The `--ig-*` tokens, with the add-on loaded
6	Built-in defaults	The default palette and light mode

"An option you pass" means passed, not "different from the default": a chart.foreColor set to its own default still wins. --apx-accent replaces series 1 only; the theme fills the rest. See Themes for the --apx-* tokens and named themes.

Turn it off

The add-on applies to every chart on the page. Per chart:

// Ignore the Ignite UI theme, keep the --apx-* tokens
theme: { designSystem: false }

// Ignore every token: the --apx-* tokens and Ignite UI
theme: { tokens: false }

To turn it off for every chart on the page, set it once on the global defaults:

window.Apex = { theme: { designSystem: false } }

Without the add-on, theme.designSystem does nothing.

Switching themes at runtime

The chart reads the theme on every render. When the page swaps its Ignite UI stylesheet, for example from the light to the dark variant, nothing tells the chart to render, so call refreshTokens():

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

refreshTokens() re-reads the --apx-* tokens, the named theme and the Ignite UI theme, and repaints. A mode the dark variant filled in goes back to light when the light variant returns.

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). Labels measured while the font is still loading would keep the fallback font's widths, so the chart reads the font again once it has loaded: one extra render, and none when the font is already in place. A font you pass in chart.fontFamily is yours to load and is not watched.

Other Apex products on the page

The ApexCharts add-on registers the shared Ignite UI adapter, so ApexTree, ApexSankey, 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). On a script-tag page that holds only once apexcharts.js has loaded, so load each product's own add-on for them as well. ApexCharts reads only its own add-on: a tree, sankey, gantt or maps add-on does not theme a chart. The ApexStock add-on is the exception in a bundler, because apexstock/ignite-ui loads apexcharts/features/ignite-ui itself, so it themes every chart on the page. See ApexTree, ApexSankey, ApexGantt, ApexGrid, ApexMaps and ApexStock.

Live theming with var() colors

The add-on reads the theme when the chart renders. To have parts of a chart follow a theme change with no render at all, pass var() colors in the config. This works without the add-on and in earlier releases:

const options = {
  colors: ['var(--ig-primary-seed)', 'var(--ig-secondary-seed)'],
  chart: { type: 'bar', foreColor: 'var(--ig-gray-800)' },
  grid: { borderColor: 'var(--ig-gray-300)' },
}

Chart part	Follows a theme change live?
Bar fills, line strokes, markers, data-label backgrounds, legend markers	Yes
Axis labels and gridlines	Yes
Tooltips and menus	Yes
Gradient fills (the area chart default) and patterns	No, resolved when the chart renders
Shades computed from a color (monochrome, treemap and heatmap shades)	No
The canvas renderer	No, canvas needs concrete colors
Color animations	They snap instead of easing

These are options you pass, so they rank first and the add-on's colors do not apply to them. Checked in Chrome.

Frequently asked questions

Does the add-on need a licence key?

No. Like the --apx-* tokens, it is covered by the licence you already use for ApexCharts, and it has no premium tier.

Do I need Ignite UI installed to use ApexCharts?

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

Which Ignite UI versions are supported?

Ignite UI 7.4.1 and later. The overlay surface for tooltips and menus arrives in Ignite UI 7.5; on 7.4.1 those parts keep the chart's own surface.

Does it work inside a shadow root?

Yes. The tokens are read where the chart is mounted, so a chart in a web component follows the theme the component inherits. See Shadow DOM & Web Components.