Migrating Apex Grid v2 to v3

Apex Grid 3.0 is a major release: a full visual refresh built on CSS custom-property theming, and the start of a free / pro split — Excel export moves to the new apex-grid-enterprise package. This guide covers the breaking changes and how to update.

At a glance

Area	v2	v3
XLSX export	`grid.exportToXLSX()` on `<apex-grid>`	moved to `<apex-grid-enterprise>`
CSV export	`grid.exportToCSV()`	unchanged — still free in core
Theming	theme CSS import + `configureTheme()`	`--ag-*` CSS custom properties, no import
Default look	elevated floating-card shadow	flat 1px hairline edge

Excel (XLSX) export moved to enterprise

exportToXLSX() and the toolbar Export XLSX entry are no longer part of the community package. CSV export stays free (exportToCSV() is unchanged).

If you called grid.exportToXLSX(...) on <apex-grid>, switch to the enterprise package and element:

npm install apex-grid-enterprise

import 'apex-grid-enterprise/define';

// <apex-grid> → <apex-grid-enterprise> (drop-in: same config API)
const grid = document.querySelector('apex-grid-enterprise');
grid.exportToXLSX({ filename: 'users', sheetName: 'Users' });

<apex-grid-enterprise> is a drop-in replacement — all of your existing columns, data, and options carry over. See the Enterprise docs for installation and licensing.

If you only use CSV export, no change is needed.

Custom export formats

The toolbar export menu is now driven by a generic seam so derived grids can register their own formats:

get exportFormats(): ReadonlyArray<ExportFormat> — defaults to [{ id: 'csv', … }].
exportAs(formatId, options) — the toolbar dispatches the chosen format here.

The enterprise grid uses this seam to add the XLSX format.

CSS-variable theming (no theme import)

The grid now styles itself out of the box through --ag-* custom properties. There is no theme to import and no configureTheme() call.

Remove the v2 theme setup:

- import { setup } from 'apex-grid';
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
- setup({ theme: 'bootstrap' });
+ import 'apex-grid/define';

Rebrand by overriding tokens on apex-grid (or any ancestor) instead:

apex-grid {
  --ag-brand: #7c3aed;   /* selection, focus, accents */
  --ag-radius: 12px;      /* outer card radius */
  --ag-row-h: 40px;       /* row height */
}

The setup() helper still exists as an optional registration convenience, but its theme option is now deprecated and does not change the grid's appearance — it only forwards to igniteui-webcomponents. When igniteui-webcomponents is present the grid auto-tints from its palette (--ig-primary-500). See Styles & Themes for the full token surface.

Neutral restyle + flat edge by default

The chrome is now grayscale, with brand color reserved for genuine state (selection, focus, checkboxes, active sort) and accents. The grid host no longer paints a heavy floating-card shadow — it shows a flat 1px hairline edge by default.

To restore the v2 elevated-card look, opt back in with the new --ag-grid-shadow hook:

apex-grid { --ag-grid-shadow: var(--ag-shadow-card); } /* restore the card */
apex-grid { --ag-grid-shadow: none; }                  /* no edge at all */

Install

npm install apex-grid lit igniteui-webcomponents

import 'apex-grid/define';

lit and igniteui-webcomponents are peer dependencies. The repository is now an npm-workspaces monorepo; the community package publishes from packages/core.