ui-grid Documentation

Technical Documentation: angular-ui/ui-grid

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

[Discord Community](https://discord.gg/Baz4w8ZWN)

UI Grid — 5.x

The modern web data grid for Angular, React, and Web Components. Every feature is free and open source.

Rust, WASM implementation, egui, and native adapter source and documentation live in orneryd/uiGrid.

v5.x + is in use by my other project, NornicDB, in the web ui components (It's a high-performance golang graph+vector database if you want to take a look)

A from-scratch rewrite of the original by the original author. Same gridOptions / columnDefs / onRegisterApi api surface, modern Angular signals internals, and zero legacy baggage.

Just like the original grid, it will NEVER be monetized. This is purely my contribution to the greater community.

It proves that the datagrid cabal wants you to think it's hard to write a data grid. Well, it's not, and nobody should be paying to group data.

Live Demo & Docs | npm | Rust Project | Used by NornicDB

Why Remastered? Copy Chapter

• Original authorship — built by the same engineer who created AngularJS ui-grid, with a decade of hindsight on what worked and what didn't
• Familiar API — if you used the original ui-grid, you already know this one: gridOptions, columnDefs, onRegisterApi, gridApi.core.*
• Modern internals — shared vanilla web component core with Shadow DOM encapsulation; Angular and React wrappers are thin bridges that project framework templates into the vanilla element via slot-based portals
• No legacy — no $scope, no Bower, no Grunt, no jQuery, no module system from 2013

Feature Comparison Copy Chapter

Everything below ships free and MIT-licensed. No enterprise tier, no license keys, no per-developer fees.

Bold = features where UI Grid gives you for free what competitors charge for or don't offer at all.

Syncfusion Community license is free for companies with <$1M annual revenue, ≤5 developers, and ≤$3M outside capital. Their paid tier requires a custom quote. Kendo UI ranges $799–$1,299/dev/yr depending on support level. Prices are approximate and subject to change.

Quick Start Copy Chapter

npm install @ornery/ui-grid

The WASM runtime is installed transitively and loaded through your application
bundler. No angular.json asset entry or dist/ui-grid-wasm-web copy is needed,
and applications should not register the TypeScript pipeline as a WASM engine.

For an unbundled deployment that hosts the web-target WASM files separately,
configure their asset root before mounting a grid:

import { setUiGridWasmAssetBase } from '@ornery/ui-grid';

setUiGridWasmAssetBase('https://cdn.example.com/ui-grid-assets/');

The configured root must contain
dist/ui-grid-wasm-web/ui_grid_wasm.js and its adjacent
ui_grid_wasm_bg.wasm. If WASM initialization is unavailable, the grid remains
functional through its TypeScript fallback.

Angular Component Copy Section

import { Component } from '@angular/core';
import { GridOptions, UiGridComponent } from '@ornery/ui-grid';

@Component({
  selector: 'app-my-grid',
  imports: [UiGridComponent],
  template: `<app-ui-grid [options]="gridOptions" />`,
})
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' },
    ],
    onRegisterApi: (api) => {
      this.gridApi = api;
    },
  };
}

React Copy Section

npm install @ornery/ui-grid-react @ornery/ui-grid-core @ornery/ui-grid-vanilla

import { UiGrid } from '@ornery/ui-grid-react';
import type { GridOptions } from '@ornery/ui-grid-core';

function MyGrid() {
  const options: 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' },
    ],
  };

  return <UiGrid options={options} />;
}

Web Components (Vanilla) Copy Section

The grid's rendering engine is a framework-free custom element () built on `@ornery/ui-grid-core` with pure DOM rendering and Shadow DOM encapsulation. Both the Angular and React wrappers are thin bridges around this same element — they mount , pass options, and project framework-specific templates into it via a slot-based portal system.

npm install @ornery/ui-grid-vanilla @ornery/ui-grid-core

No-bundler browser usage is supported by the browser bundle. It includes the core runtime and registers `` when loaded:

<script type="module" src="./ui-grid-element.js"></script>

<ui-grid-element
  grid-id="static-grid"
  enable-sorting
  enable-filtering
  column-defs='[{"name":"name"},{"name":"role"}]'
  data='[{"name":"Alice","role":"Engineer"}]'
>
</ui-grid-element>

When building from this repo, npm run build:vanilla writes that file to projects/ui-grid-vanilla/dist/browser/ui-grid-element.js. Use that browser bundle for static script-tag consumption; projects/ui-grid-vanilla/dist/index.js is CommonJS and projects/ui-grid-vanilla/dist/index.mjs is the package ESM entry for bundlers or import-map setups.

Declarative HTML usage:

<ui-grid-element
  grid-id="vanilla-demo"
  title="Team Roster"
  enable-sorting
  enable-filtering
  column-defs='[
    { "name": "name" },
    { "name": "role" },
    { "name": "salary", "type": "number", "align": "end" }
  ]'
  data='[
    { "name": "Alice", "role": "Engineer", "salary": 120000 },
    { "name": "Bob", "role": "Designer", "salary": 95000 }
  ]'
>
</ui-grid-element>

<script type="module">
  import { defineStandaloneUiGridElement } from '@ornery/ui-grid-vanilla';

  await defineStandaloneUiGridElement(); // registers <ui-grid-element>
</script>

Supported declarative inputs include boolean flags (enable-sorting, enable-filtering), scalar attributes (grid-id, title, row-height), and JSON attributes (column-defs, data).

For callbacks, function-valued column definitions, or high-frequency updates, use the options property:

import { mountVanillaUiGrid } from '@ornery/ui-grid-vanilla';

await mountVanillaUiGrid(document.getElementById('app'), {
  id: 'mounted-grid',
  data: [{ name: 'Alice', role: 'Engineer' }],
  columnDefs: [{ name: 'name' }, { name: 'role' }],
});

Features Copy Chapter

• Sorting — click column headers to cycle asc/desc/none, custom comparators, programmatic API
• Filtering — per-column inputs with conditions: contains, exact, startsWith, endsWith, greaterThan, regex, custom predicates
• Row Grouping — nested multi-column grouping with collapsible group headers
• Tree View — hierarchical data with expand/collapse per node, arbitrary nesting depth
• Expandable Rows — master/detail pattern with custom templates (Angular ng-template, React render prop, or vanilla <template> slot)
• Cell Editing — inline spreadsheet-style editing with full keyboard navigation (Tab, Enter, Escape), edit-on-focus, Enter/Tab commit+move across editable columns
• Keyboard Cell Navigation — Arrow/Tab/Home/End navigation with wrap/clamp modes, focus persistence across re-renders, keyDownOverrides for custom key handling, full gridApi.cellNav surface
• Row Selection — click/shift/ctrl/drag-paint mouse selection, keyboard (Space, Ctrl+A), row-header checkbox column, select-all header, isRowSelectable hook, 13 options, 18 API methods, 3 events
• Column Resizing — drag column borders to resize, programmatic API, persisted via save/restore state
• Row Edit — dirty/saving/error row lifecycle with rowEditWaitInterval debounce, setSavePromise pattern, auto-retry on error, visual row state indicators
• Cell Validation — declarative per-column validators (built-in required, minLength, maxLength + custom), async validator support, invalid cell markers with error messages, gridApi.validate surface
• Pagination — client-side or external pagination with configurable page sizes
• Infinite Scroll — bi-directional infinite scrolling with loading state management, needLoadMoreData/needLoadMoreDataTop events, full public API
• Column Pinning — freeze columns left or right with CSS position: sticky, programmatic API, save/restore state
• Column Moving — HTML5 native drag-and-drop column reordering
• CSV Export — download visible/selected/all rows with formula-injection protection, full option matrix (separator, header filter, field callbacks, BOM compatibility)
• Excel Export — ExcelBuilder-compatible sheet data with native numeric/boolean types preserved, configurable filename/sheet/header/custom formatters
• PDF Export — pdfMake-ready document definition with orientation/page size/styles/header/footer/custom formatter, auto-download when pdfMake is available
• CSV/JSON Import — file picker or programmatic import, full CSV parser (quoted values, escaped quotes, CRLF), header-to-column mapping, integrates with row-edit for dirty marking
• Export/Import Menu — buildGridExporterMenuItems() with per-format and per-scope flags, i18n-driven menu labels
• Virtual Scrolling — virtual scroll viewport, auto-enabled at 40+ rows
• Save/Restore State — serialize and restore sort, filters, grouping, collapsed groups, pinning, column order, column widths, pagination, selection, focused cell, tree/expandable expansion, and scroll position (per-field opt-in flags)
• Auto Resize — ResizeObserver-driven viewport height recalculation
• Custom Cell Templates — Angular ng-template, React cellRenderers map (per-column render functions), vanilla <template> slots with slot-based portal projection
• Shadow DOM — encapsulated styles with CSS custom property and ::part() hooks
• Web Component — ships as ``, a framework-free vanilla custom element (@ornery/ui-grid-vanilla); Angular and React wrappers mount this same element and project templates into it
• Feature-Flag Builds — compile-time tree-shaking of unused features
• i18n — 6 locales built-in (English, Spanish, French, German, Japanese, Simplified Chinese), runtime gridApi.i18n for language switching, fallback chain (options.labels → current locale → en-US), register additional locales via gridApi.i18n.add()
• SSR Support — server-side rendering with platform-safe guards

Theming Copy Chapter

The grid renders inside Shadow DOM. Customize it via the public --ui-grid-* CSS custom properties:

.my-app {
  --ui-grid-surface: #1e1b2e;
  --ui-grid-accent: #8b5cf6;
  --ui-grid-header-background: #2d2640;
  --ui-grid-cell-color: #e2e0f0;
  --ui-grid-border-color: rgba(139, 92, 246, 0.2);
  --ui-grid-row-hover: #322e4a;
}

Legacy --app-ui-grid-* aliases remain supported as a fallback for older app themes, but new consumer theming should target only --ui-grid-*.

Target structural elements with ::part():

app-ui-grid::part(header) {
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

See docs/theming.md for the full CSS variable reference grouped by grid section, ::part() hooks, and the demo app's 4-mode theme system.

Custom Builds Copy Chapter

Ship only the features you use:

# Only sorting and filtering — everything else is tree-shaken
node scripts/build-grid.mjs --features sorting,filtering

# Bake in a locale at build time
node scripts/build-grid.mjs --features sorting,filtering,pagination --locale i18n/fr-FR.json

# See all available flags
node scripts/build-grid.mjs --list

See docs/custom-builds.md for the full feature flag table and build presets.

Documentation Copy Chapter

Interactive versions of all web documentation are also available in the live demo.

Development Copy Chapter

npm start          # Dev server at localhost:4200
npm test           # Run tests (Vitest)
npm run build      # Production build
npm run build:library   # Build the library (ng-packagr)
npm run start:vanilla   # Run the framework-neutral browser demo at 127.0.0.1:4174

Compatibility Copy Chapter

Contributing Copy Chapter

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-feature)
3. Run npm test to ensure all tests pass
4. Submit a pull request

License Copy Chapter

MIT

Overview (`projects/ui-grid-solid/README.md`) Copy Section

@ornery/ui-grid-solid

SolidJS adapter for the existing uiGrid web component. Grid behavior, state,
rendering and event subscriptions stay in the vanilla renderer and core.

Install Copy Chapter

npm install @ornery/ui-grid-solid @ornery/ui-grid-core @ornery/ui-grid-vanilla [email protected] @solidjs/[email protected]

This package is developed against [email protected]. SolidJS 1 is not supported.
Use a SolidJS JSX compiler/plugin with jsxImportSource: "@solidjs/web".

import { createSignal } from 'solid-js';
import { UiGrid, type UiGridApi } from '@ornery/ui-grid-solid';

export function App() {
  const [rows, setRows] = createSignal([{ id: 1, name: 'Alice' }]);
  let api: UiGridApi | undefined;
  return <div style={{ height: '400px' }}>
    <button onClick={() => setRows([{ id: 1, name: 'Bob' }])}>Update</button>
    <UiGrid
      options={{
        id: 'users', data: rows(), columnDefs: [{ name: 'name' }],
        rowIdentity: (row) => String(row['id']), enableSorting: true,
      }}
      onRegisterApi={(value) => { api = value; }}
      onError={(error) => console.error(error)}
    />
  </div>;
}

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 Copy Chapter

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 [email protected]
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 route example covers server
rendering, a reactive data update after hydration, and route navigation that
unmounts and remounts the grid.

Local development Copy Chapter

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 Copy Chapter

Pass cellRenderers, keyed by column name:

const cellRenderers: UiGridCellRenderers = {
  name: (context) => <strong>{String(context.value)}</strong>,
};
// Import UiGridCellRenderers from @ornery/ui-grid-solid.
<UiGrid options={options()} cellRenderers={cellRenderers} />;

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 Copy Chapter

Pass headerRenderers, also keyed by column name:

const headerRenderers: UiGridHeaderRenderers = {
  name: (context) => <strong>{context.value} (Solid)</strong>,
};
// Import UiGridHeaderRenderers from @ornery/ui-grid-solid.
<UiGrid options={options()} headerRenderers={headerRenderers} />;

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 Copy Chapter

Pass one detailRenderer and enable expandable rows:

const detailRenderer: UiGridDetailRenderer = (context) => (
  <section>
    <strong>{String(context.row['name'])}</strong>
    <span>Row {context.rowIndex}</span>
  </section>
);

<UiGrid
  options={{
    ...options(),
    enableExpandable: true,
    expandableRowHeight: 120,
  }}
  detailRenderer={detailRenderer}
/>;

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 Copy Chapter

Pass cellEditors, keyed by column name, and enable editing for the grid and
column:

const cellEditors: UiGridCellEditors = {
  role: (context) => <select
    value={context.value}
    onChange={(event) => context.setValue(event.currentTarget.value)}
  >
    <option value="Engineer">Engineer</option>
    <option value="Designer">Designer</option>
  </select>,
};

<UiGrid
  options={{
    ...options(),
    enableCellEdit: true,
    columnDefs: [{ name: 'role', enableCellEdit: true }],
  }}
  cellEditors={cellEditors}
/>;

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`) Copy Section

@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 Copy Chapter

The grid is built as a composition of autonomous custom elements, each following the @ornery/web-components pattern:

<ui-grid-element>                  ← main grid element (shadow DOM)
  ├── ui-grid-shell.html           ← declarative grid layout template
  ├── ui-grid-empty.html           ← empty/no-options state template
  │
  ├── <ui-grid-header-cell>        ← column header (sort, group, pin, resize)
  ├── <ui-grid-filter-cell>        ← column filter input (shadow DOM + .html template)
  ├── <ui-grid-body-cell>          ← data cell (class-managed, perf-optimized)
  ├── <ui-grid-group-row>          ← grouping disclosure row (shadow DOM + .html template)
  ├── <ui-grid-pagination>         ← pagination controls (shadow DOM + .html template)
  └── <ui-grid-template>           ← declarative reusable template factory

Component Pattern Copy Section

Components follow the standard @ornery/web-components lifecycle:

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:

<div class="my-class">${this.myProp}</div>

Templates are compiled at build time by @ornery/web-components/vite (or /webpack, /esbuild, /rollup).

Performance Strategy Copy Section

• 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 Copy Section

Cell and row slot templates support dual binding syntax:

Both resolve against the same context: { $implicit, value, valueText, row, column, rowIndex }.

Installation Copy Chapter

npm install @ornery/ui-grid-vanilla @ornery/ui-grid-core

Usage Copy Chapter

No-Bundler Browser Usage Copy Section

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.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>UI Grid Browser Bundle</title>
    <script type="module" src="./ui-grid-element.js"></script>
  </head>
  <body>
    <ui-grid-element
      grid-id="static-grid"
      enable-sorting
      enable-filtering
      column-defs='[{"name":"name"},{"name":"role"},{"name":"salary","type":"number","align":"end"}]'
      data='[{"name":"Alice","role":"Engineer","salary":120000},{"name":"Bob","role":"Designer","salary":95000}]'
    >
    </ui-grid-element>
  </body>
</html>

For imperative setup in the same no-bundler environment, import from that same file:

<div id="grid"></div>

<script type="module">
  import { mountVanillaUiGrid } from './ui-grid-element.js';

  await mountVanillaUiGrid(document.querySelector('#grid'), {
    id: 'static-mounted-grid',
    columnDefs: [{ name: 'name' }, { name: 'role' }],
    data: [{ name: 'Alice', role: 'Engineer' }],
    enableSorting: true,
    enableFiltering: true,
  });
</script>

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) Copy Section

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) Copy Section

<ui-grid-element
  grid-id="my-grid"
  enable-sorting
  enable-filtering
  column-defs='[{"name":"name","field":"name"},{"name":"age","field":"age","align":"end"}]'
  data='[{"name":"Alice","age":30},{"name":"Bob","age":25}]'
>
</ui-grid-element>

Custom Cell Templates (slots) Copy Section

<ui-grid-element id="grid">
  
  <template slot="cell-name">
    <strong>{{value}}</strong>
  </template>

  
  <template slot="cell-age">
    <span style="color: ${this.value > 30 ? 'red' : 'green'}">${this.value}</span>
  </template>
</ui-grid-element>

Declarative Reusable Templates Copy Section

Define reusable components from HTML alone with <template is="ui-grid-template">:

<template is="ui-grid-template" name="ui-status-badge" status="unknown">
  <style>
    :host {
      display: inline-block;
    }
    .badge {
      padding: 2px 8px;
      border-radius: 4px;
    }
    .badge-active {
      background: #d1fae5;
      color: #065f46;
    }
    .badge-inactive {
      background: #fee2e2;
      color: #991b1b;
    }
  </style>
  <span class="badge badge-${this.status}">${this.status}</span>
</template>


<ui-grid-element>
  <template slot="cell-status">
    <ui-status-badge status="{{value}}"></ui-status-badge>
  </template>
</ui-grid-element>

Bundler Setup Copy Chapter

Vite Copy Section

import { defineConfig } from 'vite';
import webComponents from '@ornery/web-components/vite';

export default defineConfig({
  plugins: [webComponents()],
});

Webpack 5 Copy Section

import webComponents from '@ornery/web-components/webpack';

export default {
  plugins: [webComponents()],
};

tsup (esbuild) Copy Section

import { defineConfig } from 'tsup';
import webComponents from '@ornery/web-components/esbuild';

export default defineConfig({
  esbuildPlugins: [webComponents()],
});

API Copy Chapter

`mountVanillaUiGrid(target, options, wasmModule?, tagName?)` Copy Section

Mount a grid into a target element. Returns the grid element.

`defineStandaloneUiGridElement(tagName?)` Copy Section

Register the `` custom element (and all sub-components).

`UIGridTemplate` Copy Section

Exported class for the <template is="ui-grid-template"> element. Auto-registered when the grid is defined.

Grid Element Properties Copy Section

See VanillaUiGridElement type — all GridOptions fields are available as both HTML attributes and JS properties.

Overview (`openspec/changes/fix-wasm-runtime-loading/README.md`) Copy Section

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`) Copy Section

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`) Copy Section

Getting Started

Get up and running with @ornery/ui-grid in under five minutes.

Install Copy Chapter

npm install @ornery/ui-grid

Peer dependencies: @angular/core, @angular/common, rxjs, tslib.

Minimal Angular Setup Copy Chapter

The grid ships as a standalone component — no module imports required:

import { Component } from '@angular/core';
import { GridOptions, UiGridComponent } from '@ornery/ui-grid';

@Component({
  selector: 'app-my-grid',
  imports: [UiGridComponent],
  template: `<app-ui-grid [options]="gridOptions" />`,
})
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 Copy Chapter

React Copy Chapter

npm install @ornery/ui-grid-react @ornery/ui-grid-core

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 <UiGrid options={options} />;
}

Web Components Copy Chapter

Vanilla (`@ornery/ui-grid-vanilla`) Copy Section

Framework-free, pure DOM with Shadow DOM. zero dependencies:

npm install @ornery/ui-grid-vanilla @ornery/ui-grid-core

Declarative setup now works directly in HTML:

<ui-grid-element
  grid-id="vanilla-demo"
  enable-sorting
  enable-filtering
  column-defs='[{"name":"name"},{"name":"role"}]'
  data='[{"name":"Alice","role":"Engineer"}]'
>
</ui-grid-element>

<script type="module">
  import { defineStandaloneUiGridElement } from '@ornery/ui-grid-vanilla';

  await defineStandaloneUiGridElement();
</script>

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:

<script type="module" src="./ui-grid-element.js"></script>

<ui-grid-element
  grid-id="static-grid"
  enable-sorting
  enable-filtering
  column-defs='[{"name":"name"},{"name":"role"}]'
  data='[{"name":"Alice","role":"Engineer"}]'
>
</ui-grid-element>

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.

<ui-grid-element id="my-grid"></ui-grid-element>

<script type="module">
  import { defineStandaloneUiGridElement } from '@ornery/ui-grid-vanilla';

  await defineStandaloneUiGridElement();

  const grid = document.querySelector('#my-grid');
  grid.gridId = 'vanilla-props';
  grid.enableSorting = true;
  grid.enableFiltering = true;
  grid.columnDefs = [{ name: 'name' }, { name: 'role' }];
  grid.data = [{ name: 'Alice', role: 'Engineer' }];
</script>

The original bulk options property remains available when you need callbacks or function-valued configuration:

<ui-grid-element id="my-grid"></ui-grid-element>

<script type="module">
  import { defineStandaloneUiGridElement } from '@ornery/ui-grid-vanilla';

  await defineStandaloneUiGridElement();

  document.querySelector('#my-grid').options = {
    id: 'vanilla-demo',
    data: [{ name: 'Alice', role: 'Engineer' }],
    columnDefs: [{ name: 'name' }, { name: 'role' }],
  };
</script>

Run the Demo Locally Copy Chapter

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 Copy Chapter

• Features — see everything the grid can do
• Theming — customize colors and layout via CSS custom properties
• API Reference — full GridOptions, GridColumnDef, and UiGridApi documentation
• Web Component — framework-neutral custom element usage
• Rust Project — Rust/WASM implementation, egui, and native adapters

Accessibility (`docs/accessibility.md`) Copy Section

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 Copy Chapter

The grid maps its structure to the WAI-ARIA grid pattern:

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 Copy Chapter

All aria-label values are sourced from the i18n GridLabels object, so they localize automatically when you provide translated labels.

Keyboard Navigation Copy Chapter

Every data cell receives tabindex="0", making the grid fully keyboard-navigable. The following keys are handled:

Grid Navigation Copy Section

Cell Editing Copy Section

A "printable character" is any single-character key pressed without Ctrl, Meta, or Alt modifiers.

Focus Management Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 guide for details.

Theming and Contrast Copy Chapter

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 Copy Chapter

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`) Copy Section

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 Copy Chapter

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 Copy Section

<ui-grid-element
  grid-id="accounts"
  title="Accounts"
  enable-sorting
  enable-filtering
  row-height="44"
  column-defs='[{"name":"name"},{"name":"status"}]'
  data='[{"name":"Acme","status":"Active"}]'
>
</ui-grid-element>

Individual JS properties Copy Section

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 Copy Section

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:

{ ...attributeOptions, ...jsPropertyOptions }

That means explicit JS property values win over declarative attributes when both are present.

GridOptions Copy Chapter

GridColumnDef Copy Chapter

UiGridApi Copy Chapter

Access the API via onRegisterApi. The API is organized into namespaces.

core Copy Section

core.on (Events) Copy Section

pagination Copy Section

expandable Copy Section

treeBase Copy Section

treeView Copy Section

pinning Copy Section

infiniteScroll Copy Section

edit Copy Section

saveState Copy Section

Cell Editing (`docs/cell-editing.md`) Copy Section

Cell Editing

Inline spreadsheet-style editing with full keyboard navigation.

Enable Editing Copy Chapter

Set enableCellEdit or enableCellEditOnFocus at the grid or column level:

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 Copy Chapter

Conditional Editing Copy Chapter

Use cellEditableCondition to allow/deny editing per row:

{
  name: 'status',
  enableCellEdit: true,
  cellEditableCondition: (ctx) => ctx.row['status'] !== 'Enterprise',
}

Edit Model Field Copy Chapter

When the column name differs from the data property you want to write to, set editModelField:

{
  name: 'owner',
  field: 'account.owner',
  editModelField: 'account.owner', // writes edited value to this path
  enableCellEdit: true,
}

API Copy Chapter

Type-Aware Editing Copy Chapter

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`) Copy Section

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 Copy Chapter

Usage Copy Chapter

# 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 Copy Chapter

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 Copy Chapter

Higher-level presets are available via the preset build script:

# Build the full preset (default)
npm run build:library:preset -- --preset=full

# Build the minimal/headless preset
npm run build:library:preset -- --preset=minimal

Expandable Rows (`docs/expandable-rows.md`) Copy Section

Expandable Rows

Master/detail pattern — expand any row to reveal a custom Angular template below it.

Setup Copy Chapter

@Component({
  template: `
    <ng-template #detail let-row>
      <div class="detail-panel">
        <h3>{{ row.name }}</h3>
        <p>Revenue: {{ row.revenue | currency }}</p>
      </div>
    </ng-template>

    <app-ui-grid [options]="gridOptions" />
  `
})
export class MyComponent {
  @ViewChild('detail') detailTemplate!: TemplateRef<any>;

  gridOptions: GridOptions = {
    id: 'master-detail',
    data: this.data,
    enableExpandable: true,
    expandableRowHeight: 120,
    expandableRowTemplate: this.detailTemplate,
    columnDefs: [
      { name: 'name' },
      { name: 'revenue', type: 'number' },
    ],
  };
}

Options Copy Chapter

Template Context Copy Chapter

The template receives a GridExpandableTemplateContext:

API Copy Chapter

Expandable vs Tree View Copy Chapter

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`) Copy Section

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 Copy Chapter

Sorting Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

Build custom bundles with only the features you need:

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 for details.

I18n (`docs/i18n.md`) Copy Section

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) Copy Chapter

Runtime Override Copy Chapter

Pass partial overrides via GridOptions.labels:

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 Copy Chapter

Bake in a complete locale file at build time. This replaces en-US.json during the build:

node scripts/build-grid.mjs --locale projects/ui-grid/src/lib/grid/i18n/fr-FR.json

Creating a Locale File Copy Chapter

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 Copy Chapter

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:

See the Accessibility guide for the full a11y documentation.

Theming (`docs/theming.md`) Copy Section

Theming

UI Grid uses Shadow DOM encapsulation. All visual customization flows through CSS custom properties and ::part() selectors.

The runtime styles now normalize theme resolution around the public --ui-grid-* token names again. Legacy --app-ui-grid-* aliases still work as a fallback, but consumer themes should target the public --ui-grid-* surface.

How It Works Copy Chapter

The grid component renders inside a Shadow DOM boundary. Parent styles cannot leak in. Instead, the grid exposes two theming surfaces:

1. CSS custom properties — set --ui-grid-* variables on any ancestor element. They pierce the shadow boundary. Legacy --app-ui-grid-* aliases remain supported as fallback input for older app themes.
2. ::part() selectors — target specific structural elements by their part name for full CSS access.

All public styling tokens follow the --ui-grid-* naming pattern.

Recommended Override Pattern Copy Chapter

.my-app {
  --ui-grid-surface: #1e1b2e;
  --ui-grid-accent: #8b5cf6;
  --ui-grid-header-background: #2d2640;
  --ui-grid-cell-color: #e2e0f0;
  --ui-grid-border-color: rgba(139, 92, 246, 0.2);
  --ui-grid-row-hover: #322e4a;
}

If you already ship older --app-ui-grid-* theme tokens, they still work as a compatibility fallback. New consumer themes should use only --ui-grid-*.

CSS Custom Properties Copy Chapter

Foundation Copy Section

Status Pills Copy Section

Shell And Hero Copy Section

Frame, Metrics, Toolbar, And Scrolling Copy Section

Header, Pinning, And Controls Copy Section

Filters Copy Section

Rows, Cells, And Editing Copy Section

Group Rows And Drag States Copy Section

Empty State And Pagination Copy Section

`::part()` Hooks Copy Chapter

Example: Custom Brand Theme Copy Chapter

.my-app {
  /* foundation */
  --ui-grid-surface: #1e1b2e;
  --ui-grid-border-color: rgba(139, 92, 246, 0.2);
  --ui-grid-header-background: #2d2640;
  --ui-grid-cell-color: #e2e0f0;
  --ui-grid-muted-color: #8b7fb0;
  --ui-grid-row-odd: #1e1b2e;
  --ui-grid-row-even: #252238;
  --ui-grid-row-hover: #322e4a;
  --ui-grid-accent: #8b5cf6;
  --ui-grid-group-background: #2d2640;

  /* structure */
  --ui-grid-radius: 16px;
  --ui-grid-shadow: 0 4px 24px rgba(0, 0, 0, 0.3);
  --ui-grid-toolbar-padding-inline: 1.5rem;
  --ui-grid-body-cell-padding-inline: 1.25rem;

  /* controls */
  --ui-grid-control-size: 2.15rem;
  --ui-grid-pin-control-transition-duration: 200ms;
  --ui-grid-pin-menu-action-size: 1.9rem;
}

/* Target specific parts for full CSS access */
.my-app app-ui-grid::part(header) {
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

Host Attribute Pattern Copy Chapter

The demo app uses data-color-mode and data-visual-mode attributes on the root component to drive a 2×2 theme matrix (dark/light × studio/wireframe). Each combination defines a full set of semantic CSS tokens that cascade into the grid:

:host([data-color-mode='dark'][data-visual-mode='default']) {
  --grid-surface: #0b1824;
  --grid-header: #112434;
  --grid-text: #ebf5f9;
  --grid-accent: #67e8f9;
  /* ...then map to --ui-grid-* on the grid container */
}

You can use this same pattern in your own app to support multiple themes without JavaScript logic. If you already have legacy --app-ui-grid-* aliases in your codebase, you can leave them in place while standardizing new theme work on the public --ui-grid-* names.

Tree View (`docs/tree-view.md`) Copy Section

Tree View

Display hierarchical data with collapsible parent/child rows.

Data Shape Copy Chapter

Nest child rows under a configurable property (default: children):

const treeData = [
  {
    name: 'Engineering',
    headcount: 42,
    children: [
      { name: 'Frontend', headcount: 18 },
      { name: 'Backend', headcount: 24 },
    ],
  },
];

const gridOptions: GridOptions = {
  id: 'org-tree',
  data: treeData,
  enableTreeView: true,
  treeChildrenField: 'children',
  treeIndent: 20,
  columnDefs: [
    { name: 'name' },
    { name: 'headcount', type: 'number' },
  ],
};

Options Copy Chapter

Filtering Copy Chapter

When a filter is active, child matches bubble up — parent rows are shown even when they don't match the filter, as long as at least one child does.

API Copy Chapter

Tree View vs Grouping Copy Chapter

Web Component (`docs/web-component.md`) Copy Section

Web Component Output (`@ornery/ui-grid-vanilla`) Copy Chapter

A framework-free custom element built on @ornery/ui-grid-core with pure DOM rendering and Shadow DOM encapsulation. The package entry points are designed for package-aware tools, and the browser bundle is designed for direct static HTML usage.

Install Copy Section

npm install @ornery/ui-grid-vanilla @ornery/ui-grid-core

Declarative HTML Usage Copy Section

This is the non-Angular custom element build. Use it in static sites, plain JavaScript apps, or any host that should not carry Angular runtime code.

For a no-bundler static host, use the browser bundle. It includes the core runtime and auto-registers `` when loaded:

<script type="module" src="./ui-grid-element.js"></script>

<ui-grid-element
  grid-id="vanilla-demo"
  title="Team Roster"
  enable-sorting
  enable-filtering
  column-defs='[
    { "name": "name" },
    { "name": "role" },
    { "name": "salary", "type": "number", "align": "end" }
  ]'
  data='[
    { "name": "Alice", "role": "Engineer", "salary": 120000 },
    { "name": "Bob", "role": "Designer", "salary": 95000 }
  ]'
>
</ui-grid-element>

After npm run build:vanilla, the file is available at projects/ui-grid-vanilla/dist/browser/ui-grid-element.js. Copy or serve that file with your static app. The package dist/index.js file is CommonJS, and dist/index.mjs is package ESM that still expects package resolution; neither is the direct browser drop-in file.

The vanilla element supports the same declarative attribute surface. Small and medium datasets can be configured directly in markup with zero grid setup JavaScript beyond registration:

<ui-grid-element
  grid-id="vanilla-demo"
  title="Team Roster"
  enable-sorting
  enable-filtering
  column-defs='[
    { "name": "name" },
    { "name": "role" },
    { "name": "salary", "type": "number", "align": "end" }
  ]'
  data='[
    { "name": "Alice", "role": "Engineer", "salary": 120000 },
    { "name": "Bob", "role": "Designer", "salary": 95000 }
  ]'
>
</ui-grid-element>

<script type="module">
  import { defineStandaloneUiGridElement } from '@ornery/ui-grid-vanilla';

  await defineStandaloneUiGridElement(); // registers <ui-grid-element>
</script>

Supported declarative inputs include:

• Boolean attributes such as enable-sorting, enable-filtering, enable-grouping, enable-pinning, enable-pagination, and enable-virtualization
• JSON attributes such as column-defs, data, grouping, and pagination-page-sizes

Use the declarative surface for static pages, docs, CMS-rendered content, and simple embeds. For callbacks like onRegisterApi or function-based column logic, use the options property.

Performance Guidance Copy Section

• Best use for declarative attributes: initial mount, static markup-first pages, and infrequent option changes.
• Cost of declarative updates: changing JSON attributes such as data or column-defs forces the element to parse the new payload, merge options again, and may trigger more DOM work than necessary for live feeds.
• Best use for imperative updates: callbacks, one-shot bulk configuration, host-framework integration, and any case where application code already owns the current row set.
• High-frequency updates: for streaming or trading-style feeds, mount declaratively if you want, but switch live row updates to grid.setData(rows) instead of replacing the data attribute. setData(rows) is the vanilla element's cheapest update path because it patches the existing grid surface instead of re-running the full declarative sync flow.

JavaScript Property Usage Copy Section

The vanilla element also exposes individual JS properties that mirror the declarative attributes. This is useful when a framework or host app wants property binding without constructing a full options object:

<ui-grid-element id="my-grid"></ui-grid-element>

<script type="module">
  import { defineStandaloneUiGridElement } from '@ornery/ui-grid-vanilla';

  await defineStandaloneUiGridElement();

  const grid = document.querySelector('#my-grid');
  grid.gridId = 'vanilla-props';
  grid.title = 'Team Roster';
  grid.enableSorting = true;
  grid.enableFiltering = true;
  grid.columnDefs = [
    { name: 'name' },
    { name: 'role' },
    { name: 'salary', type: 'number', align: 'end' },
  ];
  grid.data = [
    { name: 'Alice', role: 'Engineer', salary: 120000 },
    { name: 'Bob', role: 'Designer', salary: 95000 },
  ];
  grid.paginationPageSizes = [10, 25, 50];
</script>

Full `options` Usage Copy Section

<ui-grid-element id="my-grid"></ui-grid-element>

<script type="module">
  import { defineStandaloneUiGridElement } from '@ornery/ui-grid-vanilla';

  await defineStandaloneUiGridElement(); // registers <ui-grid-element>

  document.querySelector('#my-grid').options = {
    id: 'vanilla-demo',
    data: [
      { name: 'Alice', role: 'Engineer', salary: 120000 },
      { name: 'Bob', role: 'Designer', salary: 95000 },
    ],
    columnDefs: [
      { name: 'name' },
      { name: 'role' },
      { name: 'salary', type: 'number', align: 'end' },
    ],
  };
</script>

Mount Helper Copy Section

The mountVanillaUiGrid helper registers the element, creates it, sets options, and appends it to a target element in one call:

import { mountVanillaUiGrid } from '@ornery/ui-grid-vanilla';

const grid = await mountVanillaUiGrid(document.getElementById('app'), {
  id: 'mounted-grid',
  data: myData,
  columnDefs: myColumns,
});

To use the optional WASM engine with the vanilla element, install and pass the compiled module published by the Rust project:

npm install @ornery/ui-grid-wasm

import { mountVanillaUiGrid } from '@ornery/ui-grid-vanilla';
import * as wasmModule from '@ornery/ui-grid-wasm';

const grid = await mountVanillaUiGrid(
  document.getElementById('app'),
  { id: 'wasm-grid', data: myData, columnDefs: myColumns },
  wasmModule,
);

If no WASM module is provided, or if WASM initialization fails, the grid automatically falls back to the JavaScript engine.

Slot Templates Copy Section

The vanilla element supports <template> elements with slot attributes for custom cell and expandable row content. Templates use {{ expression }} interpolation:

<ui-grid-element id="my-grid">
  <template slot="cell-name">
    <strong>{{ value }}</strong>
  </template>
  <template slot="expandable-row">
    <p>Details for {{ row.name }}</p>
  </template>
</ui-grid-element>

State API Copy Section

The vanilla element exposes getState() and setState() methods for save/restore:

const state = grid.getState(); // returns GridSaveState | null
grid.setState(state); // applies a previously saved state

Shared: Setting Options Copy Chapter

Shared Grid Configuration Surface Copy Chapter

Both outputs accept the same GridOptions object as the Angular component, plus the same declarative attributes for common markup-first setup:

For both elements, the options property is the advanced escape hatch rather than the only configuration path. Prefer attributes when they are sufficient; use options when you need callbacks, function-valued column definitions, or one-shot bulk assignment.

In performance terms, think of the surfaces like this:

• Declarative attributes optimize for authoring convenience and HTML-first setup.
• options assignment optimizes for programmatic control and coarse reconfiguration.
• Vanilla setData(rows) optimizes for repeated row-data refreshes and is the preferred path for high-frequency updates.

const grid = document.querySelector('ui-grid-element');
grid.options = {
  id: 'my-grid',
  data: myData,
  columnDefs: myColumns,
  enableSorting: true,
  enableFiltering: true,
  onRegisterApi: (api) => {
    window.gridApi = api;
  },
};

Shared: Styling Copy Chapter

Both variants use Shadow DOM. Style them via CSS custom properties on an ancestor:

.my-container {
  --ui-grid-surface: #1a1a2e;
  --ui-grid-cell-color: #e0e0e0;
  --ui-grid-accent: #00d4aa;
  --ui-grid-border-color: rgba(0, 212, 170, 0.2);
  --ui-grid-header-background: #242440;
}

Shared: Events Copy Chapter

Use onRegisterApi in the options to receive the grid API, then subscribe to events:

grid.options = {
  // ...
  onRegisterApi: (api) => {
    api.core.on.sortChanged((column, direction) => {
      console.log('Sort:', column, direction);
    });

    api.edit.on.afterCellEdit((row, col, newVal, oldVal) => {
      console.log('Edited:', col, oldVal, '->', newVal);
    });
  },
};

See orneryd/ui-grid for Rust implementation and native adapter documentation.

--- METRICS ---

• Files Extracted: 16
• Estimated Token Budget: ~27728 tokens
• Canonical Reference: https://codewiki.google/github.com/angular-ui/ui-grid