;
}
```
`options` uses the existing `GridOptions` type. Replace options/data through
signals; mutating a plain array in place does not notify Solid. Top-level
reactive option getters are tracked. Updates assign options to the same element,
preserving the controller's interactive state. Give the parent a definite height.
`onRegisterApi` receives a compatible `UiGridApi` whose mutating operations also
refresh the Solid renderer bridges; `options.onRegisterApi` also runs. As in
vanilla, registration callbacks may run again on options updates.
Use `api.core.on` and other existing API event groups for subscriptions, and
dispose application-owned subscriptions with Solid's `onCleanup`.
## Lifecycle and SSR
The server export renders only a host div. The vanilla module is dynamically
imported inside a client effect. Disposing the component cancels pending mount
work and removes the element, invoking vanilla's `disconnectedCallback` cleanup.
Initialization failures call `onError` when supplied, otherwise surface globally.
**Correction to the contribution plan:** the published `solid-js@2.0.0-rc.4`
package does not export `onMount`. This adapter uses SolidJS's two-argument
`createEffect` with a constant client guard for mounting, and a separate tracked
effect for options. It does not use `onSettled` as a mount hook.
Source exports use the `solid` condition so SolidStart can compile for its target.
Precompiled browser and server ESM exports are also included.
The [`examples/solid-start`](examples/solid-start) route example covers server
rendering, a reactive data update after hydration, and route navigation that
unmounts and remounts the grid.
## Local development
```sh
npm ci --prefix projects/ui-grid-solid
npm run build:solid
npm run test:solid
npm run start:solid
```
`build:solid` builds core, vanilla, then Solid using a cross-platform Node script.
In PowerShell environments that block npm.ps1, use `npm.cmd` for these commands.
## Solid JSX cells
Pass `cellRenderers`, keyed by column name:
```tsx
const cellRenderers: UiGridCellRenderers = {
name: (context) => {String(context.value)},
};
// Import UiGridCellRenderers from @ornery/ui-grid-solid.
;
```
Each renderer runs under the grid's Solid context and receives reactive getters
for `value`, `$implicit`, `row`, `column`, and `rowIndex`. Read these getters
inside JSX or tracked computations; do not destructure them into plain values.
Cell-local signals survive value updates while the slot remains mounted.
The bridge follows vanilla slot events and API row updates. Removed/virtualized
cells dispose their Solid roots. Replacing a renderer function remounts its
cells; removing it restores vanilla rendering. Keep renderer functions stable
when local state should survive. Grid teardown removes all renderer roots and
the bridge's API subscription.
Renderer failures are reported through `onError`. The failed cell stays isolated
from the grid and remounts on the next options update, allowing it to recover.
The API returned by `onRegisterApi` wraps `core.benchmark()` so its result and
`benchmarkComplete` event include completion of the Solid renderer bridge.
The demo loads 100,000 rows across three columns by default. Click **Move Name column** to exercise
`api.core.moveColumn()`.
## Solid JSX headers
Pass `headerRenderers`, also keyed by column name:
```tsx
const headerRenderers: UiGridHeaderRenderers = {
name: (context) => {context.value} (Solid),
};
// Import UiGridHeaderRenderers from @ornery/ui-grid-solid.
;
```
Header context exposes reactive `value`, `$implicit`, and `column` getters.
Local signals survive title and column option updates while the header remains
mounted. Hiding or removing a column disposes its root; showing it mounts a new
root. Renderer failures call `onError` and retry on the next options update.
Clicking a projected header cycles sorting through ascending, descending, and
none. An interactive child can call `event.preventDefault()` to suppress that
sort for its click. Programmatic column movement through
`api.core.moveColumn()` keeps projected headers aligned with the grid. A custom
header replaces the vanilla header contents, so it should render any additional
controls the application needs.
## Solid JSX expandable details
Pass one `detailRenderer` and enable expandable rows:
```tsx
const detailRenderer: UiGridDetailRenderer = (context) => (
{String(context.row['name'])}Row {context.rowIndex}
);
;
```
Import `UiGridDetailRenderer` from `@ornery/ui-grid-solid`. The renderer receives
reactive `row`, `$implicit`, `rowIndex`, and `expanded` getters. Its Solid root
stays mounted while the same expanded detail remains visible, so local state
survives data updates, sorting, and index changes.
Use the existing `api.expandable.toggleRowExpansion()`, `expandAllRows()`, and
`collapseAllRows()` operations to control details. Collapsing, filtering out,
virtualizing out, or removing a row disposes its detail root. Errors are isolated
through `onError` and retry on the next options update.
## Solid JSX cell editors
Pass `cellEditors`, keyed by column name, and enable editing for the grid and
column:
```tsx
const cellEditors: UiGridCellEditors = {
role: (context) => ,
};
;
```
Import `UiGridCellEditors` from `@ornery/ui-grid-solid`. The reactive context
contains `value`, `$implicit`, `row`, `column`, `rowIndex`, `setValue`, `commit`,
and `cancel`. The first input, select, textarea, or focusable element receives
focus when editing starts.
Enter commits, Escape cancels, and moving focus outside the editor commits.
The Solid editor bridge follows the public editing events and uses vanilla's
internal editor input to synchronize values. The existing Grid API remains
responsible for parsing typed values, updating nested fields, raising edit
events, validation, and restoring cell rendering.
Buttons can invoke `context.commit()` or `context.cancel()` directly. The Solid
root is disposed whenever the edit session ends or the grid unmounts. Renderer
failures call `onError` and retry on the next options update.
---
### Overview (`projects/ui-grid-vanilla/README.md`)
# @ornery/ui-grid-vanilla
A vanilla Web Components wrapper for `@ornery/ui-grid-core`. Renders a high-performance data grid as a custom element with no framework dependency.
## Architecture
The grid is built as a composition of autonomous custom elements, each following the `@ornery/web-components` pattern:
```
← main grid element (shadow DOM)
├── ui-grid-shell.html ← declarative grid layout template
├── ui-grid-empty.html ← empty/no-options state template
│
├── ← column header (sort, group, pin, resize)
├── ← column filter input (shadow DOM + .html template)
├── ← data cell (class-managed, perf-optimized)
├── ← grouping disclosure row (shadow DOM + .html template)
├── ← pagination controls (shadow DOM + .html template)
└── ← declarative reusable template factory
```
### Component Pattern
Components follow the standard `@ornery/web-components` lifecycle:
```js
import template from './my-component.html';
class MyComponent extends HTMLElement {
// 1. Attach shadow DOM in constructor
constructor() {
super();
this.attachShadow({ mode: 'open' });
}
// 2. Declare instance properties as template context
myProp = 'default';
// 3. Render in connectedCallback
connectedCallback() {
this.myProp = this.getAttribute('data-my-prop') ?? 'default';
template(this).connect(); // auto-renders into shadowRoot
}
}
```
The `.html` template uses ES6 template literal syntax:
```html
${this.myProp}
```
Templates are compiled at build time by `@ornery/web-components/vite` (or `/webpack`, `/esbuild`, `/rollup`).
### Performance Strategy
- **Hot-path components** (`ui-grid-body-cell`, `ui-grid-header-cell`) skip `template().connect()` entirely — the parent pre-renders innerHTML as a string, and the component only manages CSS classes via `attributeChangedCallback`. This avoids DOM construction overhead per cell.
- **Low-frequency components** (`ui-grid-filter-cell`, `ui-grid-group-row`, `ui-grid-pagination`) use full `template(this).connect()` with shadow DOM for encapsulation and declarative rendering.
### Template Bindings
Cell and row slot templates support dual binding syntax:
| Syntax | Example | Description |
| ------- | --------------- | ----------------------------------------------------- |
| `{{ }}` | `{{value}}` | Mustache-style, original grid syntax |
| `${ }` | `${this.value}` | ES6 template literal, `@ornery/web-components` native |
Both resolve against the same context: `{ $implicit, value, valueText, row, column, rowIndex }`.
## Installation
```bash
npm install @ornery/ui-grid-vanilla @ornery/ui-grid-core
```
## Usage
### No-Bundler Browser Usage
Use the browser bundle when a static HTML host needs to consume the grid without Vite, Webpack, tsup, or another package-aware build step. The bundle includes `@ornery/ui-grid-core` and registers `` when the module loads.
After `npm run build:vanilla` from the repo root, the browser-ready file is written to `projects/ui-grid-vanilla/dist/browser/ui-grid-element.js`.
```html
UI Grid Browser Bundle
```
For imperative setup in the same no-bundler environment, import from that same file:
```html
```
The package `dist/index.js` file is CommonJS for Node/package consumers, and `dist/index.mjs` is package ESM for bundlers or import-map setups. Use `dist/browser/ui-grid-element.js` for direct browser loading.
### Imperative (JavaScript)
```js
import { mountVanillaUiGrid } from '@ornery/ui-grid-vanilla';
const grid = await mountVanillaUiGrid(document.getElementById('grid'), {
id: 'my-grid',
columnDefs: [
{ name: 'name', field: 'name', displayName: 'Name' },
{ name: 'age', field: 'age', displayName: 'Age', align: 'end' },
],
data: [
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 },
],
enableSorting: true,
enableFiltering: true,
});
```
### Declarative (HTML attributes)
```html
```
### Custom Cell Templates (slots)
```html
{{value}}${this.value}
```
### Declarative Reusable Templates
Define reusable components from HTML alone with ``:
```html
${this.status}
```
## Bundler Setup
### Vite
```js
import { defineConfig } from 'vite';
import webComponents from '@ornery/web-components/vite';
export default defineConfig({
plugins: [webComponents()],
});
```
### Webpack 5
```js
import webComponents from '@ornery/web-components/webpack';
export default {
plugins: [webComponents()],
};
```
### tsup (esbuild)
```ts
import { defineConfig } from 'tsup';
import webComponents from '@ornery/web-components/esbuild';
export default defineConfig({
esbuildPlugins: [webComponents()],
});
```
## API
### `mountVanillaUiGrid(target, options, wasmModule?, tagName?)`
Mount a grid into a target element. Returns the grid element.
### `defineStandaloneUiGridElement(tagName?)`
Register the `` custom element (and all sub-components).
### `UIGridTemplate`
Exported class for the `` element. Auto-registered when the grid is defined.
### Grid Element Properties
See `VanillaUiGridElement` type — all `GridOptions` fields are available as both HTML attributes and JS properties.
---
### Overview (`openspec/changes/fix-wasm-runtime-loading/README.md`)
# fix-wasm-runtime-loading
Bundle and initialize the UI Grid WASM runtime through published package dependencies instead of application-relative demo assets.
---
### Overview (`projects/ui-grid-solid/examples/solid-start/README.md`)
# SolidStart v2 example
Create a SolidStart v2 application, install the four packages shown in the
adapter README, then copy `src/routes/index.tsx` and `src/routes/about.tsx` into
the application's routes directory. SolidStart renders the grid host on the
server; the adapter imports and mounts the vanilla custom element after
hydration in the browser.
The links exercise route navigation. Leaving `/` unmounts the grid, including
its renderer roots and subscriptions. Returning to `/` creates a fresh grid.
SolidStart v2 uses `vite.config.ts` with `solidStart()` and a deployment plugin.
Keep the generated configuration from the SolidStart scaffold; this example
only replaces the route files.
---
### Getting Started (`docs/getting-started.md`)
# Getting Started
Get up and running with `@ornery/ui-grid` in under five minutes.
## Install
```bash
npm install @ornery/ui-grid
```
**Peer dependencies:** `@angular/core`, `@angular/common`, `rxjs`, `tslib`.
## Minimal Angular Setup
The grid ships as a standalone component — no module imports required:
```typescript
import { Component } from '@angular/core';
import { GridOptions, UiGridComponent } from '@ornery/ui-grid';
@Component({
selector: 'app-my-grid',
imports: [UiGridComponent],
template: ``,
})
export class MyGridComponent {
gridOptions: GridOptions = {
id: 'my-grid',
data: [
{ name: 'Alice', role: 'Engineer', salary: 120000 },
{ name: 'Bob', role: 'Designer', salary: 95000 },
],
columnDefs: [
{ name: 'name' },
{ name: 'role' },
{ name: 'salary', type: 'number', align: 'end' },
],
};
}
```
## Required GridOptions Fields
| Field | Type | Description |
| ------------ | -------------------------- | ----------------------------------------------------------- |
| `id` | `string` | Unique grid identifier (used for CSV filenames and row IDs) |
| `data` | `readonly GridRecord[]` | Array of row objects |
| `columnDefs` | `readonly GridColumnDef[]` | Column definitions — each needs at minimum a `name` |
## React
```bash
npm install @ornery/ui-grid-react @ornery/ui-grid-core
```
```tsx
import { UiGrid } from '@ornery/ui-grid-react';
import type { GridOptions } from '@ornery/ui-grid-core';
const options: GridOptions = {
id: 'react-grid',
data: [{ name: 'Alice', role: 'Engineer' }],
columnDefs: [{ name: 'name' }, { name: 'role' }],
};
function App() {
return ;
}
```
## Web Components
### Vanilla (`@ornery/ui-grid-vanilla`)
Framework-free, pure DOM with Shadow DOM. zero dependencies:
```bash
npm install @ornery/ui-grid-vanilla @ornery/ui-grid-core
```
Declarative setup now works directly in HTML:
```html
```
Or bind the same fields as individual JS properties:
For static HTML hosts with no package-aware build step, use the browser bundle emitted by `npm run build:vanilla`:
```html
```
The repo build writes this file to `projects/ui-grid-vanilla/dist/browser/ui-grid-element.js`. It includes `@ornery/ui-grid-core` and auto-registers the element.
```html
```
The original bulk `options` property remains available when you need callbacks or function-valued configuration:
```html
```
## Run the Demo Locally
```bash
git clone https://github.com/orneryd/ui-grid.git
cd ui-grid
npm ci
npm start
```
Open `http://localhost:4200` to see the full demo with 100,000 rows, theming, and all features active. The live demo includes dedicated pages for Angular, React, and Web Components.
## Next Steps
- [Features](./features.md) — see everything the grid can do
- [Theming](./theming.md) — customize colors and layout via CSS custom properties
- [API Reference](./api-reference.md) — full GridOptions, GridColumnDef, and UiGridApi documentation
- [Web Component](./web-component.md) — framework-neutral custom element usage
- [Rust Project](https://github.com/orneryd/uiGrid) — Rust/WASM implementation, egui, and native adapters
---
### Accessibility (`docs/accessibility.md`)
# Accessibility
UI Grid is built with accessibility as a core concern. The grid applies WAI-ARIA grid semantics, supports full keyboard navigation, manages focus across editing and scrolling, and routes all visible text through the i18n system so screen reader announcements localize automatically.
## ARIA Roles
The grid maps its structure to the [WAI-ARIA grid pattern](https://www.w3.org/WAI/ARIA/apd/pattern/grid/):
| Element | Role | Notes |
|---------|------|-------|
| Grid container | `grid` | Top-level landmark; `aria-label` set from `options.title` (defaults to `"Data grid"`) |
| Header row | `row` | Contains column headers |
| Header cell | `columnheader` | One per visible column |
| Body container | `rowgroup` | Groups all data rows |
| Data row | `row` | One per visible record |
| Data cell | `gridcell` | Contains cell content or editor |
| Group row | `row` | Collapsible group header with `aria-expanded` |
| Pagination | `navigation` | `aria-label` from `labels.paginationPage` |
When tree view or expandable rows are active, `aria-expanded` is set on the toggle buttons to communicate open/closed state to assistive technology.
## aria-* Attributes
| Attribute | Where | Value |
|-----------|-------|-------|
| `aria-label` | Grid container | `options.title` or `"Data grid"` |
| `aria-label` | Sort buttons | Dynamic: `"Sort"`, `"Sort ascending"`, `"Sort descending"` (from i18n labels) |
| `aria-label` | Group toggle buttons | `"Group by this column"` / `"Remove grouping"` |
| `aria-label` | Tree toggle buttons | `"Collapse"` / `"Expand"` |
| `aria-label` | Expand detail buttons | `"Expand row"` / `"Collapse row"` |
| `aria-label` | Filter inputs | `"Filter {column name}"` |
| `aria-label` | Cell editor input | Column display name |
| `aria-label` | Pagination nav | `"Page"` |
| `aria-label` | Previous/Next buttons | `"Previous"` / `"Next"` |
| `aria-sort` | Column headers | `"ascending"`, `"descending"`, or `"none"` |
| `aria-expanded` | Tree/expand/group toggles | `true` or `false` |
| `aria-hidden` | Decorative SVG icons | `true` (with `focusable="false"`) |
All `aria-label` values are sourced from the i18n `GridLabels` object, so they localize automatically when you provide translated labels.
## Keyboard Navigation
Every data cell receives `tabindex="0"`, making the grid fully keyboard-navigable. The following keys are handled:
### Grid Navigation
| Key | Action |
|-----|--------|
| `Arrow Left` | Move focus one cell left (wraps to previous row) |
| `Arrow Right` | Move focus one cell right (wraps to next row) |
| `Arrow Up` | Move focus one row up |
| `Arrow Down` | Move focus one row down |
| `Tab` | Move to next cell (same as Arrow Right) |
| `Shift + Tab` | Move to previous cell (same as Arrow Left) |
| `Enter` | Move down one row (Shift+Enter = up) |
### Cell Editing
| Key | Action |
|-----|--------|
| `F2` | Begin editing the focused cell (if editable) |
| `Backspace` / `Delete` | Clear cell value and enter edit mode |
| Any printable character | Begin editing with that character as initial input |
| `Escape` | Cancel edit, restore original value, return focus to cell |
| `Enter` | Commit edit, move focus down (Shift = up) |
| `Tab` | Commit edit, move focus to next cell (Shift = previous) |
A "printable character" is any single-character key pressed without Ctrl, Meta, or Alt modifiers.
## Focus Management
Focus management operates inside the grid's Shadow DOM:
- **Cell focus** — after keyboard navigation or virtual scroll repositioning, `focusGridRenderedCell()` queries the shadow root for the target cell by `data-row-id` and `data-col-name` attributes. A `requestAnimationFrame` retry handles cases where Angular hasn't rendered the target cell yet.
- **Editor focus** — when a cell enters edit mode, `focusGridEditor()` finds the editor input in the shadow root and calls `input.select()` to select all text.
- **Cancellation** — a focus token prevents stale focus calls from previous navigation actions.
## Screen Reader Support
Visually hidden text (`.sr-only` / `.ui-grid-sr-only`) provides labels where icon-only buttons or implicit context would otherwise leave screen reader users without information:
- Sort buttons include hidden text matching the `aria-label`
- Group toggle buttons include hidden text for the action
- Filter cells include a hidden `"Filter {column name}"` label
- Group disclosure rows include hidden `"Collapse group"` / `"Expand group"` text
- Pagination Previous/Next icon buttons include hidden text
The `.sr-only` class uses the standard clip technique (1px box, `overflow: hidden`, `clip: rect(0,0,0,0)`), available as both `.sr-only` and `.ui-grid-sr-only` in the grid's Shadow DOM styles.
## Localized Announcements
Every screen reader label flows through the `GridLabels` i18n system. When you provide translated labels (via `GridOptions.labels` at runtime or a baked-in locale at build time), all ARIA labels and screen reader text update automatically. See the [Internationalization](./i18n.md) guide for details.
## Theming and Contrast
The grid's CSS custom property system supports high-contrast themes:
- Override `--ui-grid-cell-color`, `--ui-grid-muted-color`, `--ui-grid-surface`, and `--ui-grid-accent` to meet WCAG contrast ratios
- The `data-color-mode` / `data-visual-mode` attribute pattern (used in the demo app) demonstrates how to provide accessible light and dark modes without JavaScript theme-switching logic
- Focus indicators use the `--ui-grid-accent` color for sort indicators and active states
## Custom Cell Templates
When providing custom cell templates via `cellTemplate` or `cellRenderer`, ensure your content is accessible:
- Use semantic HTML elements where possible
- Add `aria-label` or `aria-labelledby` to interactive elements
- Ensure custom controls are keyboard-reachable (`tabindex="0"` on interactive elements)
- Maintain sufficient color contrast in custom-rendered content
---
### Api Reference (`docs/api-reference.md`)
# API Reference
Complete reference for `GridOptions`, `GridColumnDef`, and the `UiGridApi` runtime surface.
All types are exported from `@ornery/ui-grid-core`. The Angular package (`@ornery/ui-grid`) re-exports them for convenience.
## Vanilla Custom Element Surface
The vanilla web component (`@ornery/ui-grid-vanilla`) supports three equivalent configuration styles for the subset of `GridOptions` that can be expressed without functions:
### Declarative attributes
```html
```
### Individual JS properties
```javascript
const grid = document.querySelector('ui-grid-element');
grid.gridId = 'accounts';
grid.title = 'Accounts';
grid.enableSorting = true;
grid.enableFiltering = true;
grid.rowHeight = 44;
grid.columnDefs = [{ name: 'name' }, { name: 'status' }];
grid.data = [{ name: 'Acme', status: 'Active' }];
```
### Full `options` object
```javascript
grid.options = {
id: 'accounts',
data: [{ name: 'Acme', status: 'Active' }],
columnDefs: [{ name: 'name' }, { name: 'status' }],
enableSorting: true,
enableFiltering: true,
onRegisterApi: (api) => {
window.gridApi = api;
},
};
```
Use attributes or individual properties for static configuration. Use `options` for callbacks like `onRegisterApi`, function-valued column definitions such as `valueGetter`, `sortingAlgorithm`, and `cellRenderer`, or when you prefer a single bulk assignment.
The vanilla merge order is:
```text
{ ...attributeOptions, ...jsPropertyOptions }
```
That means explicit JS property values win over declarative attributes when both are present.
## GridOptions
| Field | Type | Default | Description |
| ---------------------------- | -------------------------------------------------- | ---------- | ------------------------------------------ |
| `id` | `string` | required | Unique grid identifier |
| `data` | `readonly GridRecord[]` | required | Row data array |
| `columnDefs` | `readonly GridColumnDef[]` | required | Column definitions |
| `title` | `string` | — | Grid heading text |
| `rowHeight` | `number` | 44 | Row height in pixels |
| `headerRowHeight` | `number` | — | Header row height override |
| `emptyMessage` | `string` | — | Message when no rows match |
| `labels` | `Partial` | en-US | i18n string overrides |
| `enableSorting` | `boolean` | true | Enable column sorting |
| `enableFiltering` | `boolean` | true | Enable filter row |
| `enableGrouping` | `boolean` | false | Enable row grouping |
| `grouping` | `{ groupBy?: string[]; startCollapsed?: boolean }` | — | Grouping configuration |
| `enableColumnMoving` | `boolean` | false | Enable drag-and-drop column reorder |
| `enablePinning` | `boolean` | — | Enable column pinning (freeze left/right) |
| `enableVirtualization` | `boolean` | auto | virtual scroll (auto at 40+ rows) |
| `virtualizationThreshold` | `number` | 40 | Row count that triggers virtualization |
| `enablePagination` | `boolean` | false | Enable pagination |
| `enablePaginationControls` | `boolean` | true | Show pagination UI |
| `useExternalPagination` | `boolean` | false | Grid skips local slicing |
| `paginationPageSize` | `number` | — | Rows per page |
| `paginationPageSizes` | `number[] \| null` | — | Page size selector options |
| `paginationCurrentPage` | `number` | — | Initial page |
| `totalItems` | `number` | — | Total for external pagination |
| `enableExpandable` | `boolean` | false | Enable expandable detail rows |
| `expandableRowHeight` | `number` | 150 | Detail row height |
| `expandableRowHeaderWidth` | `number` | — | Width of the expand toggle column |
| `expandableRowTemplate` | `TemplateRef` | — | Angular template for detail content |
| `expandableRowScope` | `Record` | — | Extra template context variables |
| `enableTreeView` | `boolean` | false | Enable hierarchical tree display |
| `treeChildrenField` | `string` | 'children' | Property name for child rows |
| `treeIndent` | `number` | 10 | Pixels per indent level |
| `showTreeExpandNoChildren` | `boolean` | true | Show toggle for childless rows |
| `treeRowHeaderAlwaysVisible` | `boolean` | false | Always show expand column |
| `enableCellEdit` | `boolean` | false | Enable inline cell editing |
| `enableCellEditOnFocus` | `boolean` | false | Enter edit mode on cell focus |
| `cellEditableCondition` | `boolean \| (ctx) => boolean` | — | Grid-level edit guard |
| `enableAutoResize` | `boolean` | false | ResizeObserver-driven viewport height |
| `infiniteScrollRowsFromEnd` | `number` | — | Threshold rows from end to trigger load |
| `infiniteScrollUp` | `boolean` | — | Enable upward infinite scroll |
| `infiniteScrollDown` | `boolean` | — | Enable downward infinite scroll |
| `rowIdentity` | `(row, i) => string` | — | Custom row ID function |
| `benchmark` | `{ iterations?: number }` | — | Render benchmark configuration |
| `onRegisterApi` | `(api) => void` | — | Callback to receive the UiGridApi instance |
## GridColumnDef
| Field | Type | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `name` | `string` | Column identifier (also the default data key) |
| `displayName` | `string` | Header label (auto-titleized from name if absent) |
| `field` | `string` | Dot-path into data record (e.g. `'address.city'`) |
| `type` | `'string' \| 'number' \| 'boolean' \| 'date' \| 'object'` | Data type hint for sorting and editing |
| `width` | `string` | CSS grid track value (e.g. `'200px'`, `'minmax(10rem, 1fr)'`) |
| `align` | `'start' \| 'center' \| 'end'` | Cell text alignment |
| `visible` | `boolean` | Hide column when false |
| `sortable` | `boolean` | Column-level sort override |
| `enableSorting` | `boolean` | Alias for sortable |
| `filterable` | `boolean` | Column-level filter override |
| `enableFiltering` | `boolean` | Alias for filterable |
| `enableGrouping` | `boolean` | Allow grouping by this column |
| `enablePinning` | `boolean` | Allow pinning this column |
| `pinnedLeft` | `boolean` | Pin this column to the left on init |
| `pinnedRight` | `boolean` | Pin this column to the right on init |
| `enableCellEdit` | `boolean` | Column-level edit override |
| `enableCellEditOnFocus` | `boolean` | Edit starts on focus for this column |
| `cellEditableCondition` | `boolean \| (ctx) => boolean` | Column-level edit guard |
| `editModelField` | `string` | Dot-path for writing edited values |
| `sort` | `{ direction?: SortDirection; priority?: number; ignoreSort?: boolean }` | Initial sort configuration |
| `filter` | `{ term?: unknown; condition?: FilterCondition \| RegExp \| Function; flags?: { caseSensitive?: boolean; date?: boolean }; rawTerm?: boolean; noTerm?: boolean }` | Filter configuration |
| `sortingAlgorithm` | `(a, b) => number` | Custom sort comparator |
| `formatter` | `(value, row) => string` | Display value formatter |
| `valueGetter` | `(row) => unknown` | Custom value extractor |
| `cellTemplate` | `TemplateRef` | Angular template for cell content |
| `cellRenderer` | `(ctx) => string` | HTML string cell renderer |
## UiGridApi
Access the API via `onRegisterApi`. The API is organized into namespaces.
### core
| Method | Description |
| --------------------------------- | ------------------------------------- |
| `refresh()` | Force a full pipeline re-run |
| `queueGridRefresh()` | Alias for `refresh()` |
| `queueRefresh()` | Alias for `refresh()` |
| `refreshRows()` | Alias for `refresh()` |
| `getVisibleRows()` | Get currently visible GridRow objects |
| `sortColumn(name, direction?)` | Programmatic sort |
| `setFilter(name, value)` | Set a column filter |
| `clearAllFilters()` | Clear all active filters |
| `groupByColumn(name)` | Add/remove a column from grouping |
| `clearGrouping()` | Remove all grouping |
| `moveColumn(from, to)` | Reorder columns by index |
| `exportCsv()` | Download visible rows as CSV |
| `benchmark(iterations?)` | Run render benchmark |
| `setRowInvisible(row, reason?)` | Hide a row programmatically |
| `clearRowInvisible(row, reason?)` | Un-hide a row |
### core.on (Events)
| Event | Callback Signature |
| --------------------------- | ---------------------------------- |
| `renderingComplete` | `(api) => void` |
| `sortChanged` | `(columnName, direction) => void` |
| `filterChanged` | `(filters) => void` |
| `groupingChanged` | `(groupBy) => void` |
| `columnOrderChanged` | `(order) => void` |
| `rowsVisibleChanged` | `(rows) => void` |
| `rowsRendered` | `(rows) => void` |
| `scrollBegin` / `scrollEnd` | `() => void` |
| `canvasHeightChanged` | `(oldHeight, newHeight) => void` |
| `gridDimensionChanged` | `(oldH, oldW, newH, newW) => void` |
| `benchmarkComplete` | `(result) => void` |
### pagination
| Method | Description |
| ------------------------------------------ | -------------------------- |
| `nextPage()` / `previousPage()` | Navigate pages |
| `seek(page)` | Jump to a specific page |
| `setPageSize(n)` | Change rows per page |
| `getPage()` / `getTotalPages()` | Current page info |
| `getFirstRowIndex()` / `getLastRowIndex()` | Row index range |
| `on.paginationChanged` | `(page, pageSize) => void` |
### expandable
| Method | Description |
| --------------------------------------- | ------------------------- |
| `toggleRowExpansion(row)` | Toggle a single row |
| `expandAllRows()` / `collapseAllRows()` | Bulk expand/collapse |
| `toggleAllRows()` | Toggle all rows |
| `on.rowExpandedStateChanged` | `(row, expanded) => void` |
### treeBase
| Method | Description |
| --------------------------------------- | -------------------------- |
| `toggleRowTreeState(row)` | Toggle tree node expansion |
| `expandRow(row)` / `collapseRow(row)` | Explicit expand/collapse |
| `expandAllRows()` / `collapseAllRows()` | Bulk operations |
| `getRowChildren(row)` | Get child GridRow objects |
| `on.rowExpanded` / `on.rowCollapsed` | `(row) => void` |
### treeView
| Method | Description |
| -------------------- | -------------------------------- |
| `getTreeView()` | Get current tree expansion state |
| `setTreeView(state)` | Bulk set expansion state |
### pinning
| Method | Description |
| ---------------------------- | --------------------------------------------- |
| `pinColumn(name, direction)` | Pin a column left, right, or unpin (`'none'`) |
| `on.columnPinned` | `(columnName, direction) => void` |
### infiniteScroll
| Method | Description |
| ------------------------------------------- | ------------------------------- |
| `dataLoaded(scrollUp?, scrollDown?)` | Signal that new data is loaded |
| `resetScroll(scrollUp?, scrollDown?)` | Reset to fresh state |
| `saveScrollPercentage()` | Persist scroll position ratio |
| `setScrollDirections(up, down)` | Toggle scroll directions |
| `dataRemovedTop(scrollUp?, scrollDown?)` | Signal rows removed from top |
| `dataRemovedBottom(scrollUp?, scrollDown?)` | Signal rows removed from bottom |
| `on.needLoadMoreData` | `() => void` |
| `on.needLoadMoreDataTop` | `() => void` |
### edit
| Method / Event | Description |
| --------------------------------- | ---------------------------------------- |
| `beginCellEdit(row, col, event?)` | Start editing a cell |
| `endCellEdit()` | Commit the current edit |
| `cancelCellEdit()` | Cancel without committing |
| `getEditingCell()` | Returns current editing position or null |
| `on.beginCellEdit` | `(row, col, event) => void` |
| `on.afterCellEdit` | `(row, col, newVal, oldVal) => void` |
| `on.cancelCellEdit` | `(row, col) => void` |
### saveState
| Method | Description |
| ---------------- | --------------------------------------- |
| `save()` | Returns a serializable `GridSavedState` |
| `restore(state)` | Applies a previously saved state |
---
### Cell Editing (`docs/cell-editing.md`)
# Cell Editing
Inline spreadsheet-style editing with full keyboard navigation.
## Enable Editing
Set `enableCellEdit` or `enableCellEditOnFocus` at the grid or column level:
```typescript
const gridOptions: GridOptions = {
enableCellEditOnFocus: true, // grid-level: edit on cell focus
columnDefs: [
{ name: 'name', enableCellEdit: true }, // this column is editable
{ name: 'revenue', enableCellEdit: false }, // this column is read-only
],
};
```
## Keyboard Navigation
| Key | Action |
|-----|--------|
| `F2` or `Enter` | Begin editing focused cell |
| Any printable key | Begin editing and replace value |
| `Backspace` / `Delete` | Clear value and begin editing |
| `Tab` | Commit and move to next editable cell |
| `Shift + Tab` | Commit and move to previous editable cell |
| `Enter` | Commit and move down |
| `Shift + Enter` | Commit and move up |
| `Escape` | Cancel edit, restore original value |
## Conditional Editing
Use `cellEditableCondition` to allow/deny editing per row:
```typescript
{
name: 'status',
enableCellEdit: true,
cellEditableCondition: (ctx) => ctx.row['status'] !== 'Enterprise',
}
```
## Edit Model Field
When the column name differs from the data property you want to write to, set `editModelField`:
```typescript
{
name: 'owner',
field: 'account.owner',
editModelField: 'account.owner', // writes edited value to this path
enableCellEdit: true,
}
```
## API
| Method / Event | Description |
|----------------|-------------|
| `gridApi.edit.beginCellEdit(row, colName)` | Start editing programmatically |
| `gridApi.edit.endCellEdit()` | Commit the current edit |
| `gridApi.edit.cancelCellEdit()` | Cancel without committing |
| `gridApi.edit.getEditingCell()` | Returns the current editing position or null |
| `gridApi.edit.on.beginCellEdit` | `(row, col, event) => void` |
| `gridApi.edit.on.afterCellEdit` | `(row, col, newVal, oldVal) => void` |
| `gridApi.edit.on.cancelCellEdit` | `(row, col) => void` |
## Type-Aware Editing
The editor input type adapts to the column's `type`:
- `'number'` → ``
- `'date'` → ``
- default → ``
Value parsing is automatic: numeric strings become `Number`, `'true'`/`'false'` become booleans, and date strings remain as-is.
---
### Custom Builds (`docs/custom-builds.md`)
# Custom Builds
Ship only the features you use. The build script generates compile-time boolean constants that let the bundler tree-shake unused code paths entirely.
## Feature Flags
| CLI Name | TypeScript Constant | What It Guards |
|----------|-------------------|----------------|
| `sorting` | `FEATURE_SORTING` | Column sort UI and pipeline sort step |
| `filtering` | `FEATURE_FILTERING` | Filter row and pipeline filter step |
| `grouping` | `FEATURE_GROUPING` | Group headers and grouping pipeline |
| `pagination` | `FEATURE_PAGINATION` | Pagination footer and page slicing |
| `cell-edit` | `FEATURE_CELL_EDIT` | Inline editing UI and keyboard handlers |
| `expandable` | `FEATURE_EXPANDABLE` | Expandable detail rows |
| `tree-view` | `FEATURE_TREE_VIEW` | Tree row rendering and tree pipeline |
| `infinite-scroll` | `FEATURE_INFINITE_SCROLL` | Infinite scroll state machine |
| `column-moving` | `FEATURE_COLUMN_MOVING` | drag-and-drop on headers |
| `csv-export` | `FEATURE_CSV_EXPORT` | CSV export and toolbar button |
| `save-state` | `FEATURE_SAVE_STATE` | Save/restore state serialization |
| `auto-resize` | `FEATURE_AUTO_RESIZE` | ResizeObserver integration |
## Usage
```bash
# Full build (default — all features enabled)
node scripts/build-grid.mjs
# Minimal build — only sorting and filtering
node scripts/build-grid.mjs --features sorting,filtering
# Custom locale baked in at build time
node scripts/build-grid.mjs --locale projects/ui-grid/src/lib/grid/i18n/fr-FR.json
# Both features and locale
node scripts/build-grid.mjs --features sorting,filtering,pagination --locale i18n/fr-FR.json
# See available flags
node scripts/build-grid.mjs --list
# Dry run — writes generated file but skips ng build
node scripts/build-grid.mjs --features sorting --dry-run
```
## How It Works
1. The script backs up `grid.features.ts`
2. Generates a new version with only selected flags set to `true`
3. Optionally swaps `i18n/en-US.json` with the provided locale file
4. Runs `ng build uiGridPackage --configuration production`
5. Restores the original files (even on build failure)
The bundler sees `if (false) { ... }` and tree-shakes the dead code path entirely. The grid API uses noop fallbacks for all optional feature namespaces, so runtime behavior is always safe.
## Build Presets
Higher-level presets are available via the preset build script:
```bash
# Build the full preset (default)
npm run build:library:preset -- --preset=full
# Build the minimal/headless preset
npm run build:library:preset -- --preset=minimal
```
| Preset | Includes | Status |
|--------|----------|--------|
| `full` | All features + Angular component | Supported |
| `minimal` | Headless core: API, sorting, filtering, pagination | Supported |
| `data-heavy` | Sorting, filtering, viewport, export | Planned |
| `interactive` | Sorting, filtering, grouping, editing, tree, expandable | Planned |
---
### Expandable Rows (`docs/expandable-rows.md`)
# Expandable Rows
Master/detail pattern — expand any row to reveal a custom Angular template below it.
## Setup
```typescript
@Component({
template: `
{{ row.name }}
Revenue: {{ row.revenue | currency }}
`
})
export class MyComponent {
@ViewChild('detail') detailTemplate!: TemplateRef;
gridOptions: GridOptions = {
id: 'master-detail',
data: this.data,
enableExpandable: true,
expandableRowHeight: 120,
expandableRowTemplate: this.detailTemplate,
columnDefs: [
{ name: 'name' },
{ name: 'revenue', type: 'number' },
],
};
}
```
## Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableExpandable` | `boolean` | `false` | Enable expandable rows |
| `expandableRowHeight` | `number` | `150` | Min height of the detail row (px) |
| `expandableRowTemplate` | `TemplateRef` | — | Angular template for the detail content |
| `expandableRowHeaderWidth` | `number` | — | Width of the expand toggle column |
| `expandableRowScope` | `Record` | — | Extra variables injected into template context |
## Template Context
The template receives a `GridExpandableTemplateContext`:
| Property | Type | Description |
|----------|------|-------------|
| `$implicit` | `GridRecord` | The row data (use with `let-row`) |
| `row` | `GridRecord` | Same as `$implicit` |
| `rowIndex` | `number` | Index of the row in the current view |
| `expanded` | `boolean` | Always `true` when the template renders |
## API
| Method | Description |
|--------|-------------|
| `gridApi.expandable.toggleRowExpansion(row)` | Toggle a single row |
| `gridApi.expandable.expandAllRows()` | Expand all rows |
| `gridApi.expandable.collapseAllRows()` | Collapse all rows |
| `gridApi.expandable.toggleAllRows()` | Toggle all rows |
| `gridApi.expandable.on.rowExpandedStateChanged` | `(row, expanded) => void` |
## Expandable vs Tree View
**Expandable rows** show custom template content below a data row (master/detail). **Tree view** shows child data rows that share the same column structure as parents. You can use both simultaneously.
---
### Features (`docs/features.md`)
# Features
Every feature is included free and open source. No enterprise tier, no license keys. Features can be individually tree-shaken at build time via compile-time feature flags.
## Feature Overview
| Feature | Option Flag | Default | Description |
| ------------------ | --------------------------- | ------- | ------------------------------------------------------------------- |
| Sorting | `enableSorting` | `true` | Click column headers to cycle asc / desc / none |
| Filtering | `enableFiltering` | `true` | Per-column filter inputs with configurable conditions |
| Row Grouping | `enableGrouping` | `false` | Nested multi-column grouping with collapsible headers |
| Tree View | `enableTreeView` | `false` | Hierarchical data with expand/collapse per node |
| Expandable Rows | `enableExpandable` | `false` | Master/detail pattern with custom Angular templates |
| Cell Editing | `enableCellEdit` | `false` | Inline spreadsheet-style editing with keyboard nav |
| Pagination | `enablePagination` | `false` | Client-side or external pagination |
| Infinite Scroll | `infiniteScrollRowsFromEnd` | — | Bi-directional infinite scroll with loading state |
| Column Moving | `enableColumnMoving` | `false` | Drag-and-drop column reordering |
| CSV Export | `gridApi.core.exportCsv()` | — | Export visible rows with formula-injection protection |
| Virtual Scrolling | `enableVirtualization` | auto | virtual scroll, auto-enabled at 40+ rows |
| Save/Restore State | `gridApi.saveState` | — | Serialize sort, filter, grouping, pagination, expansion state |
| Auto Resize | `enableAutoResize` | `false` | ResizeObserver-driven viewport height recalculation |
| Custom Templates | `cellTemplate` | — | Angular ng-template for fully custom cell rendering |
| Shadow DOM | always | — | Encapsulated styles with CSS custom property and `::part()` hooks |
| Web Component | `npm run build:vanilla` | — | Ship as `` for package or no-bundler browser usage |
| SSR Support | automatic | — | Server-side rendering with platform-safe guards |
| i18n | `labels` | en-US | Override any UI string at runtime or bake in a locale at build time |
## Sorting
- Enabled by default (`enableSorting: true`)
- Click a column header to cycle: none → ascending → descending → none
- Per-column disable: `column.sortable = false`
- Custom comparator: `column.sortingAlgorithm = (a, b) => number`
- Programmatic: `gridApi.core.sortColumn('name', 'asc')`
## Filtering
- Enabled by default (`enableFiltering: true`)
- Built-in conditions: `contains`, `startsWith`, `endsWith`, `exact`, `notEqual`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`
- Wildcard support: terms with `*` auto-compile to regex
- Custom predicates: `column.filter.condition = (term, value, row, column) => boolean`
- RegExp conditions: `column.filter.condition = /pattern/i`
## Row Grouping
- Requires `enableGrouping: true`
- Multiple columns: `grouping: { groupBy: ['status', 'company'] }`
- Start collapsed: `grouping: { startCollapsed: true }`
- Per-column disable: `column.enableGrouping = false`
- Mutually exclusive with Tree View
## Compile-Time Feature Flags
Build custom bundles with only the features you need:
```bash
node scripts/build-grid.mjs --features sorting,filtering
```
Disabled features compile to `false` constants — the bundler tree-shakes all guarded code paths. See [Custom Builds](./custom-builds.md) for details.
---
### I18n (`docs/i18n.md`)
# Internationalization
Override any UI string at runtime via the `labels` option, or bake in a complete locale file at build time.
## Default Labels (en-US)
| Key | Default Value |
|-----|---------------|
| `sortDefault` | Sort |
| `sortAsc` | Sort ascending |
| `sortDesc` | Sort descending |
| `groupColumn` | Group by this column |
| `ungroupColumn` | Ungroup this column |
| `groupCollapse` | Collapse group |
| `groupExpand` | Expand group |
| `treeCollapse` | Collapse |
| `treeExpand` | Expand |
| `expandDetail` | Expand row |
| `collapseDetail` | Collapse row |
| `filterPlaceholder` | Filter... |
| `filterDisabled` | Filter disabled |
| `filterColumn` | Filter this column |
| `paginationPrevious` | Previous |
| `paginationNext` | Next |
| `paginationPage` | Page |
| `paginationOf` | of |
| `paginationRows` | rows |
| `emptyHeading` | No data |
| `emptyDescription` | No rows to display |
| `toolbarOf` | of |
| `toolbarRows` | rows |
| `statsVisibleRows` | visible rows |
| `groupRowsSuffix` | rows |
## Runtime Override
Pass partial overrides via `GridOptions.labels`:
```typescript
const gridOptions: GridOptions = {
id: 'my-grid',
data: myData,
columnDefs: myColumns,
labels: {
filterPlaceholder: 'Filtrer...',
emptyHeading: 'Aucune donnée',
emptyDescription: 'Aucune ligne à afficher',
paginationPrevious: 'Précédent',
paginationNext: 'Suivant',
},
};
```
## Build-Time Locale
Bake in a complete locale file at build time. This replaces `en-US.json` during the build:
```bash
node scripts/build-grid.mjs --locale projects/ui-grid/src/lib/grid/i18n/fr-FR.json
```
## Creating a Locale File
1. Copy `projects/ui-grid/src/lib/grid/i18n/en-US.json`
2. Translate all 26 keys
3. Save as a new JSON file (e.g. `fr-FR.json`)
4. The file must use the same key names — only the values change
## ARIA Labels and Screen Readers
All interactive elements in the grid derive their `aria-label` values from the `GridLabels` object. When you provide translated labels, screen reader announcements localize automatically — no additional configuration is needed.
Labels that flow into ARIA attributes:
| Label Key | ARIA Usage |
|-----------|------------|
| `sortDefault` / `sortAsc` / `sortDesc` | `aria-label` on sort buttons |
| `groupColumn` / `ungroupColumn` | `aria-label` on group toggle buttons |
| `groupCollapse` / `groupExpand` | Screen reader text on group disclosure rows |
| `treeCollapse` / `treeExpand` | `aria-label` on tree toggle buttons |
| `expandDetail` / `collapseDetail` | `aria-label` on expand/collapse detail buttons |
| `filterColumn` | Screen reader text prefix for filter inputs (`"Filter {column}"`) |
| `paginationPrevious` / `paginationNext` | `aria-label` on pagination buttons |
| `paginationPage` | `aria-label` on the pagination `