Using with Ignite UI
Grids follow an Ignite UI theme through an add-on. One import turns it on: the brand, text and muted text, gridlines and the pinned-column edge, the header, the state colors, the font, the apex-grid-enterprise popups, and light or dark then come from the theme's --ig-* tokens, and follow a theme change live. The add-on needs no extra licence key, since the licence you run the grid under already covers it, and it ranks below every --ag-* token you set.
Changed in 4.0. In 3.x the grid picked up
--ig-primary-*and the Ignite UI font with no import. From 4.0 it reads no--ig-*token without the add-on, and an Ignite UI stylesheet alone changes nothing. Add the import below to keep, and widen, the old behavior. See Migrating v3 to v4.
Opt in
Import the add-on once, next to the grid:
import 'apex-grid/define'
import 'apex-grid/ignite-ui'
The grid ships as ES modules with bare imports, so load the add-on the same way you load the grid: through your build tool or dev server. It is listed as a side effect in the package, so a bundler keeps a bare import of it.
Every grid on the page, in the document or in any shadow root, then follows the Ignite UI theme the page loads, including grids that connected before the import. Without the add-on the grid reads no --ig-* token.
What follows the theme
| Grid part | Ignite UI token |
|---|---|
| Brand | --ig-primary-* |
| Text and muted text, gridlines, the pinned-column edge | The gray ramp |
| Header | --ig-surface-raised (Ignite UI 7.5 and later) |
| State colors | The theme's state colors |
| Font | --ig-font-family |
| Enterprise popups (filter builder, set filter, AI panel, tool panel, status bar) | --ig-surface-overlay (Ignite UI 7.5 and later, else the grid's own popup colors) |
| Light or dark | --ig-theme-variant |
- The card and row surfaces keep the grid's own light or dark background.
- A grid without
theme="dark"ortheme="light"follows the Ignite UI variant declared on:rootor any ancestor, and switches live when the theme does.theme="light"keeps a grid light (text and lines then keep the built-in values, since a dark theme's grays are light) andtheme="dark"keeps it dark. Where the browser has no container style queries, grids follow the document's variant. - While the add-on is loaded, the tokens that follow Ignite UI leave the root defaults, as
--ag-brandand--ag-fontalways have, so page CSS that reads one should give its own fallback:var(--ag-text, #111827).
Ranking
Every Apex product resolves its look in the same order, highest first. Ignite UI fills only what nothing above it set. The grid themes through CSS rather than color options and has no named themes, so for a grid the order is: your --ag-* tokens, then the --apx-* tokens, then Ignite UI, then the built-in values.
| Rank | Source | In Apex Grid |
|---|---|---|
| 1 | An option you pass | The grid has no color options; theme="dark" or theme="light" fixes the mode |
| 2 | The product's own CSS variables | --ag-brand, --ag-text, --ag-overlay and the other --ag-* and --ag-dark-* tokens |
| 3 | The family --apx-* tokens | --apx-accent, --apx-fore, --apx-grid, --apx-surface, --apx-font-family, --apx-radius-factor |
| 4 | A named theme or palette | None in the grid |
| 5 | Ignite UI | The --ig-* tokens, with the add-on loaded |
| 6 | Built-in defaults | The grid's own blue and grays |
New in 4.0, --ag-overlay and --ag-overlay-text (--ag-dark-overlay, --ag-dark-overlay-text on a dark grid) color the enterprise popups. Set both: the popup lines, muted text and hover wash are mixed from the two. See Styles & Themes for the --ag-* tokens.
Turn it off
The add-on applies to every grid on the page. Per grid, two attributes (or the matching properties):
<!-- Ignite UI colors and font off; the variant still picks the mode -->
<apex-grid design-system="off"></apex-grid>
<!-- The family --apx-* tokens and Ignite UI off, the variant included -->
<apex-grid tokens="off"></apex-grid>
grid.designSystem = false // same as design-system="off"
grid.tokens = false // same as tokens="off"
tokens="off" also covers the content the grid renders. Without the add-on, design-system does nothing.
React
With react-apex-grid and apex-grid 4.0 or later, import the same add-on once, anywhere in the app:
import 'apex-grid/ignite-ui'
The two switches are props, typed from the element like every other prop:
// Ignite UI colors and font off (the Ignite UI variant still picks the mode)
<ApexGrid designSystem={false} data={rows} columns={columns} style={{ height: 480 }} />
// Family --apx-* tokens and Ignite UI both off, for the grid and its content
<ApexGrid tokens={false} data={rows} columns={columns} style={{ height: 480 }} />
They reflect as design-system="off" and tokens="off".
Blazor
Blazor-ApexGrid 1.2.0 bundles apex-grid 4.0, so there is no import. Turn the add-on on once in Program.cs:
using Blazor_ApexGrid;
ApexGridIgniteUI.Enable();
The component then loads _content/Blazor-ApexGrid/js/apex-grid.ignite-ui.bundle.js before the first grid initializes. To load it yourself instead, add it as a module in index.html (or App.razor):
<script type="module" src="_content/Blazor-ApexGrid/js/apex-grid.ignite-ui.bundle.js"></script>
Per grid, DesignSystem and Tokens are the two switches:
<ApexGrid TItem="Product" Data="products" Columns="columns" DesignSystem="false" />
<ApexGrid TItem="Product" Data="products" Columns="columns" Tokens="false" />
They render as design-system="off" and tokens="off". A Blazor app that relied on an Ignite UI stylesheet theming the grid in 3.x calls ApexGridIgniteUI.Enable() after upgrading to 1.2.0.
Switching themes at runtime
Nothing to call. The grid resolves the theme in CSS, so a stylesheet swap, for example from the light to the dark Ignite UI variant, restyles every grid as soon as the new sheet applies.
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 grid takes the font from CSS, so the browser swaps it in when it arrives.
Other Apex products on the page
Each product takes its own add-on. For the apex-grid-enterprise chart panel to read the theme itself, also import apexcharts/features/ignite-ui (see Using ApexCharts with Ignite UI); the grid never loads it, since it themes every chart on the page. Without it the panel chart takes the grid's colors, which follow the theme.
Frequently asked questions
Does the add-on need a licence key?
No. Whatever licence you use the grid and apex-grid-enterprise under already covers it, and the add-on has no premium tier of its own.
Do I need Ignite UI installed to use Apex Grid?
No. The grid has no Ignite UI dependency. The add-on only reads the --ig-* custom properties an Ignite UI theme declares on the page.