Using with Ignite UI
From ApexTree 2.3.0, trees can follow an Ignite UI theme loaded on the page. One import turns it on: text, borders and edges, the accent, node and command palette surfaces, the font, and light or dark then come from the theme's --ig-* tokens. Your ApexTree licence already covers the add-on, with no extra key, and it ranks below every style you set, so a tree you already themed stays as it is.
Opt in
With a bundler
Import the add-on once, before the first render():
import ApexTree from 'apextree'
import 'apextree/ignite-ui'
With script tags
Load apextree.ignite-ui.min.js, before or after apextree.min.js:
<script src="https://cdn.jsdelivr.net/npm/apextree@2.3.0/apextree.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/apextree@2.3.0/apextree.ignite-ui.min.js"></script>
Load it before the first render. A tree 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
| Tree part | Ignite UI token |
|---|---|
| Text | --ig-gray-800 |
| Borders and edges | --ig-gray-300 |
| Hover, badge and focus-ring accent | --ig-primary-seed |
fontFamily | --ig-font-family |
| Node and command palette surfaces | --ig-surface-raised, --ig-surface-overlay (Ignite UI 7.5 and later) |
| Card text, chips, hairlines and chevrons | The theme's gray steps; links and the progress fill take its primary |
| Focus-mode dim, when nothing behind the tree paints | The theme's paper |
| Light or dark | --ig-theme-variant |
- When the theme declares a dark variant and you did not pass
theme, the tree renders'dark', with the theme's colors over the dark preset's. - Text and border colors apply only while the tree's theme matches the variant.
- A card whose background you set yourself (
nodeBGColor, or--apex-tree-node-bg) keeps its own text colors, since the theme's grays suit only its own surface.
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 | fontColor, borderColor, nodeBGColor, fontFamily, theme |
| 2 | The tree's own CSS variables | --apex-tree-node-bg and the other --apex-tree-* variables |
| 3 | The family --apx-* tokens | --apx-accent, --apx-fore, --apx-grid, --apx-surface, --apx-font-family |
| 4 | A named theme | The 'dark' preset, or a registered theme |
| 5 | Ignite UI | The --ig-* tokens, with the add-on loaded |
| 6 | Built-in defaults | The light theme |
See Theming and Customization for the --apex-tree-* variables and the --apx-* tokens.
Turn it off
The add-on applies to every tree on the page. Per tree, two top-level options:
const tree = new ApexTree(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 tree reads the theme on every render. 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', () => tree.refreshTokens(), { once: true })
link.href = '/themes/material-dark.css'
refreshTokens() re-reads the --apex-tree-* variables, the --apx-* tokens, the registered theme and the Ignite UI theme, and repaints at the current zoom. Nodes, expanded cards, selection, focus mode and the active path are kept. 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 tree 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 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). 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.
Frequently asked questions
Does the add-on need a licence key?
No extra one. The licence the tree already runs under covers the add-on, and that licence is unchanged.
Do I need Ignite UI installed to use ApexTree?
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.