Home > ApexGrid Docs > Docs > Apex Grid - Installation and Getting Started

Apex Grid - Installation and Getting Started

The Apex grid is a web component built on top of Lit, couple of helper libraries, and distributed as a Javascript module.

Installation

One package, and nothing to install alongside it.

npm install apex-grid

The grid declares no peer dependencies. lit, @lit/context and @lit-labs/virtualizer are ordinary dependencies, so npm resolves them for you. The grid does not bundle them, so we suggest a modern build tool/dev server that understands ECMA modules and bare import specifiers, such as Vite.

Changed in 3.5.0. Earlier versions asked you to install lit and igniteui-webcomponents as peers. The Ignite UI dependency is gone entirely: the grid registers no Ignite UI element and the only thing it was ever used for was one inert pass-through call. Removing it takes five packages out of your lockfile. If you installed igniteui-webcomponents only for the grid, you can drop it. Nothing else changes, and --ag-* overrides and the --ig-primary-* auto-tint hooks behave exactly as before. See Styles & Themes.

Quick start

The grid registers and styles itself out of the box. Import the self-registering entry point, drop an <apex-grid> on the page, and assign its data. There is no theme stylesheet to import and no configureTheme() call. The grid renders through --ag-* CSS custom properties (see Styles & Themes).

import 'apex-grid/define';

const grid = document.createElement('apex-grid');
grid.autoGenerate = true;
grid.data = [/* … */];

document.querySelector('#app').appendChild(grid);

Upgrading from v2? Per-framework theme imports and configureTheme() have been removed, and Excel (XLSX) export has moved to apex-grid-enterprise. See the v2 → v3 migration guide.

Component registration

The Apex grid package exposes the following entry points for finer-grained setup:

apex-grid

The main entry point of the package. Exports the grid component as well as type information. This entry point is not self-registering. Make sure to call the register method on the component class to trigger the upgrade to a web component.

import { ApexGrid } from 'apex-grid';
ApexGrid.register();

apex-grid/define

Imports the grid component and automatically registers it and its dependencies in the browser customElements registry.

apex-grid/styles.css

An opt-in stylesheet that sets height: 100% with a min-height: 240px fallback on the host. Import it instead of writing your own host height rule:

import 'apex-grid/styles.css';

The grid's internal :host { display: grid } rule cannot be overridden: setting display on <apex-grid> from consumer CSS collapses the virtualizer.

setup()

An optional one-call convenience that registers the component and adopts the host height stylesheet in a single step. It is idempotent and SSR-safe (it falls back to a <style> tag where document.adoptedStyleSheets is unavailable).

import { setup } from 'apex-grid';

setup();                      // register + adopt host styles
setup({ hostStyles: false }); // register only; supply your own host sizing

The theme option is inert as of 3.5.0. It never affected the grid's appearance, because the grid styles itself through --ag-* variables regardless; all it ever did was forward to igniteui-webcomponents' configureTheme(), and that dependency is gone. Passing it now warns once on the console and does nothing else, and it will be removed in the next major version. Existing calls still compile, so nothing breaks.

If you were relying on that side effect to theme your own Ignite UI components, call configureTheme() yourself.

How To Use Apex Grid

import { ApexGrid } from 'apex-grid';

ApexGrid.register();

const grid = document.createElement('apex-grid');
grid.autoGenerate = true;
grid.data = [...];

document.querySelector('#app').appendChild(grid);

Enterprise edition

apex-grid-enterprise is the pro-licensed companion package. It registers as <apex-grid-enterprise> and is a drop-in replacement for <apex-grid> (same configuration API, columns, data binding, sorting, filtering, editing, and theming), layering on row grouping, pivoting, aggregations, integrated charts, a formula engine, cell range selection, master-detail, infinite rows, XLSX export, and an AI toolkit. See the enterprise feature guides in the sidebar (Row Grouping, Pivoting, Integrated Charts, and the rest).

Installation

Install the enterprise package alongside the community grid:

npm install apex-grid-enterprise apex-grid

apex-grid is a real dependency of the enterprise package, so npm would resolve it anyway; name it explicitly because you import from both. Enterprise 0.7.0 requires apex-grid@^3.5.0. lit and @lit/context are shared peers of the enterprise package: install a single copy of each.

apexcharts is an optional peer, needed only for the integrated charts, and it is loaded through a dynamic import(), so a grid that never charts neither bundles nor downloads it. One ApexCharts copy serves both the grid's charts and any your app draws itself.

From 0.7.0 the range is ^5.15.0 || ^6.0.0 || ^7.0.0, so ApexCharts 7 installs without a peer warning. The full enterprise suite passes identically against 5.16.0 and 7.x, and 5.x remains supported. Releases through 0.6.1 declared ^5.15.0 || ^6.0.0 and produced a warning on ApexCharts 7 (the grid still worked; the four calls it makes are unchanged).

Import the self-registering entry point and swap the tag name:

import 'apex-grid-enterprise/define';

const grid = document.createElement('apex-grid-enterprise');
grid.columns = [/* … */];
grid.data = [/* … */];
document.querySelector('#app').appendChild(grid);

Everything you configure on <apex-grid> works unchanged on <apex-grid-enterprise>.

Licensing

Licensing is offline and non-hostile. Without a valid key the grid keeps working: it renders a small watermark and logs a one-time console notice. There are no network calls and no hard blocking.

import { ApexGridEnterprise } from 'apex-grid-enterprise';

ApexGridEnterprise.setLicense('APEX-…');

Call setLicense() once, before (or shortly after) your grids mount. A valid key removes the watermark and the console notice.

Opting into features (tree-shaking)

apex-grid-enterprise/define is the batteries-included path: it registers <apex-grid-enterprise> with every feature module enabled, which pulls in all feature code. To keep the rest tree-shaken, register only the modules you use with the static use() method before constructing any grid:

import { ApexGridEnterprise } from 'apex-grid-enterprise';
import { groupingModule } from 'apex-grid-enterprise/features/grouping';
import { aggregationModule } from 'apex-grid-enterprise/features/aggregation';

ApexGridEnterprise.use(groupingModule, aggregationModule);
customElements.define(ApexGridEnterprise.tagName, ApexGridEnterprise);

use() is idempotent per module id and returns the class so calls can chain. The full set is also exported as enterpriseModules if you want the everything path without the /define side-effect import:

import { ApexGridEnterprise, enterpriseModules } from 'apex-grid-enterprise';
ApexGridEnterprise.use(...enterpriseModules);

Companion custom elements

Some enterprise features render as sibling elements you place in your markup:

Element	Tag	Purpose
`ApexGridChart`	`<apex-grid-chart>`	Live chart bound to the grid view or a selected range
`ApexGridStatusBar`	`<apex-grid-status-bar>`	Live selection aggregates (count, sum, average, min, max)
`ApexGridToolPanel`	`<apex-grid-tool-panel>`	Column + grouping management side panel
`ApexGridSetFilter`	`<apex-grid-set-filter>`	Checkbox "set" filter for a column's distinct values

See Companion Elements and Integrated Charts.