Using with Ignite UI

From ApexGantt 3.21.0, Gantt charts can follow an Ignite UI theme loaded on the page. One import turns it on: the bars, text, gridlines and arrows, the header, the tooltip, the font, and light or dark then come from the theme's --ig-* tokens. The add-on comes under the licence the chart already runs on, with no extra key, and ranks below every style you set, so a chart you already themed stays as it is.

Opt in

With a bundler

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

import ApexGantt from 'apexgantt'
import 'apexgantt/ignite-ui'

With script tags

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

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

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

What follows the theme

Gantt option	Ignite UI token
fontColor	--ig-gray-800
cellBorderColor, arrowColor	--ig-gray-300
barBackgroundColor	--ig-primary-seed
fontFamily	--ig-font-family
headerBackground	--ig-surface-raised (Ignite UI 7.5 and later)
tooltipBGColor	--ig-surface-overlay (Ignite UI 7.5 and later)
Light or dark	--ig-theme-variant

• backgroundColor and the row colors keep the theme's own.
• When the theme declares a dark variant and you passed neither theme nor backgroundColor, the chart takes the dark theme's colors for every color option you did not pass, and goes back to the light ones when the variant changes.
• Text and border colors apply only while the chart's mode matches the variant: the theme you passed (a registered theme's mode), else the variant, else what your backgroundColor reads as.
• A PNG or PDF export of a chart the variant made dark is drawn on the Ignite UI paper.

In a framework wrapper, leave the theme prop unset so the dark variant can apply: a theme the wrapper passes on, even 'light', counts as one you passed. The React, Angular and Blazor wrappers pass theme only when you set it. vue-apexgantt 1.2.0 and earlier always pass 'light', which keeps the chart light under a dark Ignite UI theme; vue-apexgantt 1.3.0 leaves it unset, and sends theme: undefined when you unset the prop.

Ranking

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

Rank	Source	Example
1	An option you pass	barBackgroundColor, fontColor, cellBorderColor, fontFamily, theme, a task's own barBackgroundColor
2	The chart's own CSS variables	--apex-gantt-font-color, --apex-gantt-grid-line and the other --apex-gantt-* variables
3	The family --apx-* tokens	--apx-accent, --apx-fore, --apx-grid, --apx-surface, --apx-font-family
4	A named theme	theme: 'dark', or the name of a theme registered on the family registry
5	Ignite UI	The --ig-* tokens, with the add-on loaded
6	Built-in defaults	The light theme

From 3.21.0, theme takes the name of a theme registered on the registry the Apex products share, as well as 'light' and 'dark'; a name nothing is registered under renders as 'light'. See Theming and Customization for the --apex-gantt-* variables and the --apx-* tokens.

Turn it off

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

const gantt = new ApexGantt(el, {
  series,
  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

Gantt has no refreshTokens(): it reads the theme when it renders. When the page swaps its Ignite UI stylesheet, for example from the light to the dark variant, call render() (or update({})) once the new sheet has loaded:

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

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 browser swaps the font into the chart's text when it arrives, but auto-sized grid columns are measured with the font in place at render time. If the chart rendered before the font arrived, render it again once the font has loaded:

document.fonts.ready.then(() => gantt.render())

Other Apex products on the page

The add-on registers the Ignite UI adapter the Apex products share, so ApexTree, ApexSankey 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 Gantt charts as well, but from a script tag only once apexcharts.js has loaded, so on a script-tag page load apexgantt.ignite-ui.min.js for the Gantt charts.

Frequently asked questions

Does the add-on need a licence key?

No. It needs no key of its own; the licence you use ApexGantt under covers it, and the add-on has no tier of its own.

Do I need Ignite UI installed to use ApexGantt?

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.