Using with Ignite UI
From ApexMaps 1.3.0, maps can follow an Ignite UI theme loaded on the page. One import turns it on: the series colors, text, borders, focus ring, tooltip and zoom controls, the font, the basemap and no-data greys, outlines, and light or dark then come from the theme's --ig-* tokens. The add-on needs no licence key of its own and ranks below every style you set, so a map you already themed stays as it is.
Opt in
With a bundler
Import the add-on once, before the first render:
import ApexMaps from 'apexmaps'
import 'apexmaps/ignite-ui'
With script tags
Load dist/apexmaps.ignite-ui.min.js, before or after apexmaps.min.js:
<script src="https://cdn.jsdelivr.net/npm/apexmaps@1.3.0/dist/apexmaps.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/apexmaps@1.3.0/dist/apexmaps.ignite-ui.min.js"></script>
Load it before the first render. A map rendered earlier picks it up on its next updateOptions(); call updateOptions({}) to apply it at once. Without an Ignite UI add-on the --ig-* tokens are ignored, with no error; the --apx-* and --apexmaps-* tokens work either way.
What follows the theme
| Map role | Ignite UI token |
|---|---|
Series rows 1 to 6: the ordinal palette, and row 1 for a bubble, marker or line series with no color | --ig-primary-seed, then the secondary, info, success, warn and error seeds (each else its -500) |
| Series rows 7 to 12, then 13 to 18 | The same six at -300, then at -700 |
| Text, muted text, borders | --ig-gray-800, --ig-gray-600, --ig-gray-300 |
| Focus ring | --ig-primary-seed |
| Tooltip and zoom controls | --ig-surface-overlay (Ignite UI 7.5 and later; the built-in surface before) |
| Basemap, no-data | --ig-gray-100, --ig-gray-200 |
| Region and symbol outlines | The paper: --ig-surface-base, else --ig-surface-500 |
| Basemap outlines | --ig-gray-300 |
| Selected outline | --ig-gray-800 |
| Font | --ig-font-family |
| Light or dark | --ig-theme-variant |
- With
theme.modeunset, a dark Ignite UI theme turns the map dark, and the map's own background stays transparent so the page's surface shows through (--apexmaps-bgandchart.backgroundstill paint). A mode you pass wins, and a light theme changes nothing about the mode. - Text, lines, surfaces and the greys apply only while the map's mode is the theme's: a dark theme's light greys never land on a light map. The series and focus colors apply in either mode.
- Sequential and diverging ramps (choropleth classes, hexbin and pixel scales) do not change.
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 | A series color, chart.background, theme.mode |
| 2 | The map's own CSS variables | --apexmaps-bg and the other --apexmaps-* variables |
| 3 | The family --apx-* tokens | --apx-accent, --apx-fore, --apx-grid, --apx-series-1 |
| 4 | A named palette | theme.palette, including a theme registered with registerTheme |
| 5 | Ignite UI | The --ig-* tokens, with the add-on loaded |
| 6 | Built-in defaults | The default palette and light mode |
--apx-accent alone takes series row 1, and the theme fills the rest. Where the theme paints the selected outline or the basemap's outlines, --apx-fore and --apx-grid rank above it. See Theming for the --apexmaps-* variables.
A dark map under a dark Ignite UI theme is on a page that says it is dark, so there the --apx-* tokens apply to the dark palette too, above the theme, as in light. Without the add-on they never reach a dark map.
Turn it off
The add-on applies to every map on the page. Per map:
// Ignore the Ignite UI theme, keep the --apx-* tokens
theme: { designSystem: false }
// Ignore every token: --apx-* and Ignite UI (your --apexmaps-* tokens still apply)
theme: { tokens: false }
Without the add-on, theme.designSystem does nothing.
Switching themes at runtime
Maps have no refreshTokens(): a map reads the theme when it renders. When the page swaps its Ignite UI stylesheet, for example from the light to the dark variant, call updateOptions({}) once the new sheet has loaded:
const link = document.getElementById('ig-theme')
link.addEventListener('load', () => map.updateOptions({}), { 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 map 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, ApexSankey and ApexGantt on the page follow the theme too. ApexCharts charts take their own add-on, apexcharts/features/ignite-ui; see Using ApexCharts with Ignite UI.
It works the other way too: another product's Ignite UI add-on on the page (the ApexCharts, ApexTree, ApexSankey, ApexGantt or ApexStock one) registers the same adapter, so maps follow the theme with it alone. Only the basemap and no-data greys need apexmaps/ignite-ui; without it they keep the built-in greys. On a script-tag page, load apexmaps.ignite-ui.min.js for the maps as well.
Frequently asked questions
Does the add-on need a licence key?
No. The map's own licence covers it and does not change, and the add-on has no premium tier.
Do I need Ignite UI installed to use ApexMaps?
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.