Framework adapters and custom elements

API reference › Framework adapters and custom elements

All 13 pages Everything on one page → Developer guide →

Framework adapters

The web component carries the grid inside it, so use it or createGrid in a page, not both: two copies keep separate registries, and a renderer registered through one is invisible to the other. One optional bundle per framework. The framework and createGrid are passed in rather than imported, so the adapters add no dependency and carry no second copy of the grid.

// React
import React from 'react';
import { createGrid } from './dist/lattice-grid.esm.js';
import { createLatticeGrid } from './dist/modules/react.esm.js';

const LatticeGrid = createLatticeGrid({ React, createGrid });
<LatticeGrid columns={columns} rows={rows} rowKey="id" onCellChanged={fn} />

// Vue 3
import * as vue from 'vue';
import { createLatticeGrid } from './dist/modules/vue.esm.js';

const LatticeGrid = createLatticeGrid({ vue, createGrid });
<LatticeGrid :columns="columns" :rows="rows" row-key="id" @cell-changed="fn" />

// Svelte, an action, so no framework runtime is needed
import { createLatticeAction } from './dist/modules/svelte.esm.js';

const lattice = createLatticeAction({ createGrid });
<div use:lattice={{ columns, rows, rowKey: 'id' }} on:cell-changed={fn}></div>

React: every viewer, not only the grid

Until 1.63 the React adapter wrapped createGrid and nothing else. Every other shipped viewer - the KPI panel, a chart, the board, the Gantt, the layout, the tab strip - and the data router had no React surface, so a React application wrote its own useEffect per viewer. It does not have to any more: there is one component per viewer, and each keeps the contract the grid component already kept.

import React from 'react';
import ReactDOM from 'react-dom';
import { createGrid } from '@toclocoinc/lattice-grid';
import { createKPI } from '@toclocoinc/lattice-grid/modules/kpi';
import { createChart } from '@toclocoinc/lattice-grid/modules/charts';
import { createDataRouter } from '@toclocoinc/lattice-grid/modules/data-router';
import { createLatticeReact } from '@toclocoinc/lattice-grid/modules/react';

// Built once, at module scope. Building components inside a component hands React a
// new type on every render, and a new type is a different element: the subtree would
// unmount and remount, destroying and rebuilding the grid on every keystroke.
const L = createLatticeReact({
  React, ReactDOM, createGrid, createKPI, createChart, createDataRouter,
});

function Dashboard({ rows }) {
  const router = L.useLatticeRouter(ROUTER_CONFIG);
  return (
    <L.LatticeRouterProvider router={router}>
      <L.LatticeGridProvider>
        <L.LatticeGrid name="quakes" route="all" {...GRID_CONFIG} rows={rows} />
        <L.LatticeKPI gridName="quakes" tiles={TILES} columns={5} />
        <L.LatticeChart gridName="quakes" type="bar" x="region" y="count" />
      </L.LatticeGridProvider>
    </L.LatticeRouterProvider>
  );
}

const A = await import('../packages/modules/react/index.js');

// A stand-in for React and react-dom. The adapter never imports either, so a
// factory only needs the handful of names it destructures - which is exactly
// why this example runs in Node with no framework installed.
const React = { createElement: () => ({}), createContext: () => ({}), forwardRef: (f) => f };
const ReactDOM = { createPortal: () => ({}) };
const stub = () => ({ on: () => () => {}, destroy() {} });

// One call builds whichever components the factories you pass support.
const L = A.createLatticeReact({
  React, ReactDOM, createGrid: stub, createKPI: stub, createChart: stub, createDataRouter: stub,
});

// …or one factory at a time.
const components = [
  A.createLatticeGrid({ React, createGrid: stub }),
  A.createLatticeKPI({ React, createKPI: stub }),
  A.createLatticeChart({ React, createChart: stub }),
  A.createLatticeKanban({ React, createKanban: stub }),
  A.createLatticeGantt({ React, createGantt: stub }),
  A.createLatticeLayout({ React, createLayout: stub }),
  A.createLatticeTabs({ React, ReactDOM, createTabs: stub }),
  A.createLatticeViewer({ React, viewer: 'kpi', mount: stub }),
].filter((c) => typeof c === 'function');

// The provider/hook pair and the router hook are built the same way.
const { LatticeGridProvider, useLatticeGrid } = A.createLatticeGridContext({ React });
const { useLatticeRouter } = A.createLatticeRouter({ React, createDataRouter: stub });

// And the lifecycle underneath, driven with no framework at all: mount once,
// push a changed live prop into the instance that already exists, destroy.
const seen = [];
const controller = A.createViewerController({
  viewer: 'kpi',
  element: {},
  props: { rows: [{ id: 1 }] },
  mount: () => ({ setRows: (r) => seen.push(r.length), on: () => () => {}, destroy() {} }),
});
controller.update({ rows: [{ id: 1 }, { id: 2 }] });
controller.destroy();

return `${components.length} components, ${A.viewerHandlerName('card:move')}, `
  + `${A.DEFAULT_GRID_NAME}, rows ${seen.join('/')}, `
  + `events ${A.VIEWER_EVENTS.kpi.length}/${Object.keys(A.VIEWER_APPLY).length}`;

Live props versus mount-time props. The grid takes any changed configuration key through one call (grid.setAll); no other viewer does. So each viewer declares which props it can take while it is running - the table above, and VIEWER_APPLY at runtime - and everything else is mount-time configuration. A mount-time prop that changes is not silently ignored and not silently remounted (that would throw away scroll position, selection and expansion): it is named once in a warning that tells you to give the component a key that changes when the rebuild is wanted, or to drive the instance through the ref.

Two props rebuild a viewer rather than update it: the grid it is bound to, and anything it cannot exist without. A chart holding a destroyed grid is not stale, it is invalid, so a new grid tears the old chart down and builds a new one against it - in that order, never the reverse.

A live feed: rowUpdates and predicates. rowUpdates is a keyed diff handed straight to grid.rows.apply(), applied when the object's identity changes - a feed produces a new change object per batch, so identity is the right trigger and re-applying the same object would re-land rows the grid already has. predicates is { name: fn } mapped to grid.filters.where(name, fn), diffed by name, with a name that has gone removed. Those compose with whatever filter the reader set in the tool panel; the filters prop cannot, because it maps to filters.set and replaces the whole condition tree.

StrictMode creates one instance. React 18's StrictMode deliberately mounts, unmounts and mounts again in development. Every component here builds its instance in an effect with an empty dependency list and destroys it in that effect's cleanup, so the first is destroyed before the second is built and exactly one survives. There is no module-level "already mounted" flag, because that would defeat a genuine remount.

Props are diffed with Object.is, and that is a promise about identity. An inline columns={[{ field: 'a' }]} is a new array on every render, so it counts as changed every render and reconfigures the grid every render. Hoist it to module scope or wrap it in useMemo. This is not a defect to work around: a deep compare of a million-row array on every render would cost more than the reload it prevents.

Sharing one rows array between grids is safe. Since 1.63 the grid copies the array it is handed on ingest, so two grids given the same rows={EMPTY} default no longer contaminate each other. The row objects are still shared, as they always were - mutate one and both grids see it.

React 18 and 19, no SSR. Nothing in the adapter uses an API added in 19 or removed in 19 (forwardRef is still supported there). Every component owns a real DOM element, so there is no server rendering and no React Server Component support: render them on the client.

One build warning is gone. The version resolver carried a Node-only fallback whose import('node:' + 'module') Vite could not analyse statically, so every Vite build of every application printed "The above dynamic import cannot be analyzed by Vite" about a line that could never run. The build now deletes that branch from every emitted artefact.

Vue 3: every viewer, not only the grid

Until 1.66 the Vue adapter wrapped createGrid and nothing else. Every other shipped viewer - the KPI panel, a chart, the board, the Gantt, the layout, the tab strip - and the data router had no Vue surface, so a Vue application wrote its own onMounted/onBeforeUnmount pair per viewer. It does not have to any more: there is one component per viewer, and each keeps the contract the grid component already kept.

Every component is built with defineComponent and a render function, so the adapter needs no template compiler in your build and runs on vue.runtime.* - the compiler-free build a Vite application ships. The floor is Vue 3.3.

// lattice.js - built once, at module scope.
import * as vue from 'vue';
import { createGrid } from '@toclocoinc/lattice-grid';
import { createKPI } from '@toclocoinc/lattice-grid/modules/kpi';
import { createChart } from '@toclocoinc/lattice-grid/modules/charts';
import { createDataRouter } from '@toclocoinc/lattice-grid/modules/data-router';
import { createLatticeVue } from '@toclocoinc/lattice-grid/modules/vue';

export const L = createLatticeVue({ vue, createGrid, createKPI, createChart, createDataRouter });

// Dashboard.vue
<script setup>
import { L } from './lattice.js';

L.provideLatticeGrids();
L.provideLatticeRouter(ROUTER_CONFIG);

const rows = shallowRef([]);
</script>

<template>
  <component :is="L.LatticeGrid" name="quakes" route="all" v-bind="GRID_CONFIG" :rows="rows" />
  <component :is="L.LatticeKPI" grid-name="quakes" :tiles="TILES" :columns="5" />
  <component :is="L.LatticeChart" grid-name="quakes" type="bar" x="region" y="count" />
</template>

const A = await import('../packages/modules/vue/index.js');

// A stand-in for Vue. The adapter never imports it, so a factory only needs
// the handful of names it destructures - which is exactly why this example
// runs in Node with no framework installed.
const vue = {
  defineComponent: (d) => d, h: () => ({}), ref: (v) => ({ value: v }),
  shallowRef: (v) => ({ value: v }), computed: (f) => ({ get value() { return f(); } }),
  watch: () => () => {}, onMounted: () => {}, onBeforeUnmount: () => {},
  onScopeDispose: () => {}, provide: () => {}, inject: () => null,
  Teleport: Symbol('Teleport'), Fragment: Symbol('Fragment'),
};
const stub = () => ({ on: () => () => {}, setRows: () => {}, destroy() {} });

// One call builds whichever components the factories you pass support.
const L = A.createLatticeVue({
  vue, createGrid: stub, createKPI: stub, createChart: stub, createDataRouter: stub,
});

// …or one factory at a time. Each returns a Vue component definition.
const components = [
  A.createLatticeGrid({ vue, createGrid: stub }),
  A.createLatticeKPI({ vue, createKPI: stub }),
  A.createLatticeChart({ vue, createChart: stub }),
  A.createLatticeKanban({ vue, createKanban: stub }),
  A.createLatticeGantt({ vue, createGantt: stub }),
  A.createLatticeLayout({ vue, createLayout: stub }),
  A.createLatticeTabs({ vue, createTabs: stub }),
].filter((c) => typeof c.setup === 'function');

// The generic behind them, the registry pair and the router composables.
A.createLatticeViewer({ vue, viewer: 'kpi', mount: stub });
const { LatticeGridProvider, useLatticeGrid } = A.createLatticeGridContext({ vue });
const { provideLatticeRouter } = A.createLatticeRouter({ vue, createDataRouter: stub });

// Events are bound under dashed names, because a colon is directive syntax.
const gridEvent = A.dashedName(A.EVENT_NAMES.find((n) => n === 'cell:changed'));
const viewerEvent = A.dashedName(A.VIEWER_EVENTS.kanban.find((n) => n === 'card:move'));
A.viewerHandlerName('card:move');

// And the lifecycle underneath, driven with no framework at all: mount once,
// push a changed live prop into the instance that already exists, destroy.
const seen = [];
const controller = A.createViewerController({
  viewer: 'kpi',
  element: {},
  props: { rows: [{ id: 1 }] },
  mount: () => ({ setRows: (r) => seen.push(r.length), on: () => () => {}, destroy() {} }),
});
controller.update({ rows: [{ id: 1 }, { id: 2 }] });
controller.destroy();
void [L.LatticeGrid, LatticeGridProvider, useLatticeGrid, provideLatticeRouter, A.VIEWER_APPLY];

return `${components.length} components, ${gridEvent}, ${viewerEvent}, `
  + `${A.DEFAULT_GRID_NAME}, rows ${seen.join('/')}`;

The grid paints outside Vue's reactivity, and that is deliberate. The adapter creates the grid in onMounted and pushes changed props into it; the grid then renders on its own schedule, not Vue's. So nextTick() tells you Vue has patched the DOM, not that the grid has painted. Measure, screenshot or scroll in a grid event - @render-done, @rows-changed, @size-changed - rather than after nextTick or in onMounted.

Hold big row arrays in a shallowRef, never a ref. ref([...100k rows]) makes every row object a reactive proxy: Vue walks the array on assignment and every property read on every row goes through a proxy trap from then on. The grid neither needs nor wants that - it re-reads the array itself when the reference changes. Use shallowRef(rows) and assign a new array when the data changes (rows.value = next), or markRaw the objects. The same goes for the grid instance you keep off a template ref: a ref would proxy the whole Grid, and the proxy is not === the object createGrid returned.

Props are diffed with Object.is, and that is a promise about identity. An inline :columns="[{ field: 'a' }]" is a new array on every render, so it counts as changed every render and reconfigures the grid every render. Hoist it to module scope or put it behind a computed. This is not a defect to work around: a deep compare of a million-row array on every render would cost more than the reload it prevents. For the same reason nothing here uses a { deep: true } watcher - one over a config carrying rows would walk every row object on every tick.

Live props versus mount-time props. The grid takes any changed configuration key through one call (grid.setAll); no other viewer does. So each viewer declares which props it can take while it is running (VIEWER_APPLY), and everything else is mount-time configuration. A mount-time prop that changes is not silently ignored and not silently remounted (that would throw away scroll position, selection and expansion): it is named once in a warning that tells you to give the component a :key that changes when the rebuild is wanted, or to drive the instance through the ref. The tab strip's whole tabs array is mount-time for the same reason - the module has no way to repaint an existing tab's label or badge.

Events are dashed; the lifecycle pair is grid-ready and grid-destroyed. cell:changed is emitted as @cell-changed, because a colon in a Vue binding is directive syntax. Every grid event is declared in emits, so none of them falls through onto the host element. The two lifecycle emits are named grid-* because ready and destroy are grid event names already re-emitted here, and the React and Angular adapters name their pair the same.

Reaching the instance, and class/style/id. A template ref on the grid exposes grid() (gridRef.value.grid()); every other component exposes instance(). Both are null before mount. class, style and id are applied to the component's own host element rather than passed on as configuration; every other binding is the viewer's configuration, with a known kebab-cased key mapped to its camelCase form (:row-key reaches rowKey), as the web component does.

Cleanup, and no SSR. Every component destroys its instance, stops its watchers and unsubscribes its listeners in onBeforeUnmount, so a v-if toggled twice leaves exactly one instance alive and an unmounted page leaves nothing on a timer or an event bus. The router is destroyed with the component whose setup provided it. Every component owns a real DOM element and builds nothing until onMounted, so a server render emits the empty host and nothing else: there is no SSR or Nuxt server-side support, and Vue 2 is not supported.

Svelte 5: components you compile, not a bundle you load

Until 1.66 the Svelte adapter was a single action, use:lattice, over a grid. An action cannot do what the other adapters do - it takes a node and a value, so it has no children, no snippets and no context of its own, and a tab strip whose panels hold Svelte-rendered content is simply out of its reach. So 1.66 adds components, one per viewer, and they ship the way the Svelte ecosystem ships components: as .svelte source, compiled by your own toolchain. svelte is an optional peer dependency; the package still installs nothing. Svelte 5 only - the components are written in runes and snippets, neither of which exists in Svelte 4. The action is unchanged and still supported.

<!-- Dashboard.svelte -->
<script>
  import Provider from '@toclocoinc/lattice-grid/svelte/GridProvider.svelte';
  import Grid from '@toclocoinc/lattice-grid/svelte/Grid.svelte';
  import KPI from '@toclocoinc/lattice-grid/svelte/KPI.svelte';
  import Chart from '@toclocoinc/lattice-grid/svelte/Chart.svelte';
  import Tabs from '@toclocoinc/lattice-grid/svelte/Tabs.svelte';

  let rows = $state.raw([]);
  let board;
</script>

<Provider>
  <Grid bind:this={board} name="quakes" class="grid" {...GRID_CONFIG} {rows}
        onCellChanged={(e) => save(e)} />
  <KPI gridName="quakes" tiles={TILES} columns={5} />
  <Chart gridName="quakes" type="bar" x="region" y="count" />

  <Tabs tabs={TABS} active={open} onTabChanged={(e) => (open = e.id)}>
    {#snippet all()}<Grid name="all" {...GRID_CONFIG} {rows} />{/snippet}
  </Tabs>
</Provider>

The components are deliberately thin - a template, the $props() plumbing, a bind:this getter and the context wiring - because they ship as source you read. Every rule they follow lives in modules/svelte, which ships minified, and each is exported so you can build a component of your own on exactly the same footing:

const S = await import('../packages/modules/svelte/index.js');

// A component hands its props straight to the helpers. They keep the
// adapter's own props out of the instance and accept a callback under
// either Svelte 5 spelling.
const split = S.adaptProps('grid', {
  rowKey: 'id', 'class': 'grid', name: 'main', oncellchanged: () => {},
});
const ready = S.pickCallback({ ongridready: () => 'called' }, 'onGridReady');

// The registry a <GridProvider> puts in context, and the grid binding a
// <Grid> drives. Both are plain functions: no Svelte here at all.
const registry = S.createGridRegistry();
const applied = [];
const fakeGrid = () => ({
  setAll: (c) => applied.push(c.theme), destroy() {},
  on: () => () => {}, rows: { apply: () => {} },
  filters: { where: () => {} },
});
const bound = S.bindGrid({
  createGrid: fakeGrid, element: {}, registry, props: { name: 'main', theme: 'light' },
});
bound.update({ name: 'main', theme: 'dark' });

// A viewer waits for its grid, then is built once. VIEWER_BINDING says
// which key its grid arrives under and what it cannot be built without.
const built = [];
const stub = () => ({ on: () => () => {}, setRows: () => {}, update: () => {}, destroy() {} });
for (const viewer of Object.keys(S.VIEWER_BINDING)) {
  const panel = S.bindViewer({
    viewer, element: {}, registry,
    factory: (...args) => { built.push(viewer); return stub(...args); },
  });
  panel.sync({ gridName: 'main' });
  panel.destroy();
}

// A tab strip claims a panel for each tab the host wrote a snippet for.
const tabs = [{ id: 'one' }, { id: 'two' }];
const props = { one: () => {} };
const strip = S.bindTabs({
  element: {},
  createTabs: (el, config) => ({ config, on: () => () => {}, destroy() {} }),
});
strip.sync({ tabs, contentIds: S.snippetTabIds(tabs, props) });
const claimed = strip.instance.config.tabs.filter((t) => t.view).map((t) => t.id);

// One router, built by the first grid that asks and destroyed with the
// component that provided it.
let routers = 0;
const handle = S.createRouterHandle({
  createDataRouter: () => { routers += 1; return { attach: () => {}, detach: () => {}, destroy: () => {} }; },
});
handle.attach({}, 'all'); handle.attach({}, 'all'); handle.destroy();

// And the call each module's factory actually takes.
S.viewerMount('chart', (opts) => opts)({}, { type: 'bar' });
void [S.GRID_REGISTRY_KEY, S.ROUTER_KEY, ready()];

return `config ${Object.keys(split.config).join(',')}; own ${split.own.name}; `
  + `registry ${registry.names().join(',')}; grid ${applied.join(',')}; `
  + `tabs ${claimed.join(',')}; viewers ${built.join(',')}; router ${routers}`;

Events are callback props. Svelte 5 removed component events, so cell:changed arrives as onCellChanged - the same name React uses. The all-lowercase oncellchanged is accepted too, for anyone who prefers Svelte's DOM attribute style. The grid's own dashed names (cell-changed) still apply to the use:lattice action, which dispatches CustomEvents on the node.

Reactivity, and rows. The grid paints outside Svelte's scheduler: it owns its element and its own render loop, and nothing inside it is reactive state. Hold large row arrays in $state.raw (or in an ordinary let), never in deep $state - a proxy over a million rows costs far more than the reload it would save, and the components diff by identity, so a new array is what signals a change. An inline literal prop (columns={[…]}) is a new array on every render and reconfigures the viewer every time; hoist it.

Cleanup, and no SSR. Every component builds its instance in onMount and destroys it in onDestroy, unsubscribing its listeners, withdrawing its grid from the registry and detaching from the router before the grid goes. Nothing is built during server rendering - SvelteKit SSR emits the empty host element and nothing else - so these components are browser-only by construction.

Angular: a compiled entry point, @toclocoinc/lattice-grid/angular

Angular's components are not objects a library can assemble at run time in a production build. modules/angular did assemble them that way, which needs Angular's JIT compiler in the page - present on a development server, absent from every AOT build. So Angular gets an entry point of its own: TypeScript components compiled by @angular/compiler-cli into a partial-Ivy library, which your build's Angular Linker turns into definitions exactly as it does for any other Angular library you install. No compiler in your bundle, and one standalone component per viewer.

It ships inside the grid package, at the subpath @toclocoinc/lattice-grid/angular: one install, one version number, one licence. @angular/core and @angular/common are optional peer dependencies of the package, so a project that is not an Angular one installs nothing extra and sees no warning.

npm install @toclocoinc/lattice-grid

import { bootstrapApplication } from '@angular/platform-browser';
import { createGrid } from '@toclocoinc/lattice-grid';
import { createKPI } from '@toclocoinc/lattice-grid/modules/kpi';
import { createChart } from '@toclocoinc/lattice-grid/modules/charts';
import {
  LatticeGridComponent, LatticeKpiComponent, LatticeChartComponent, provideLattice,
} from '@toclocoinc/lattice-grid/angular';

@Component({
  selector: 'app-dashboard',
  imports: [LatticeGridComponent, LatticeKpiComponent, LatticeChartComponent],
  template: `
    <lattice-grid #grid name="quakes" [config]="config" [quickFilter]="search()"
                  (cell-changed)="save($event)" />
    <lattice-kpi  gridName="quakes" [config]="{ tiles }" />
    <lattice-chart gridName="quakes" [config]="{ type: 'bar', x: 'region', y: 'count' }" />
  `,
})
export class Dashboard {
  // The live grid, the same object createGrid returns.
  grid = viewChild<LatticeGridComponent>('grid');
}

// Each factory is injected, not imported by the library: an application that
// shows a grid downloads the grid, and never the board or the eighteen charts.
bootstrapApplication(Dashboard, {
  providers: [provideLattice({ createGrid, createKPI, createChart })],
});

Change detection: zone or zoneless, unconfigured. The grid is created inside NgZone.runOutsideAngular, because it installs its own scroll, wheel and pointer listeners and running change detection on every scroll frame of a million-row grid is the difference between smooth and unusable. An event that reaches an output you have bound re-enters the zone, so (cell-changed)="count = count + 1" repaints exactly as you expect; an output nobody bound costs nothing. Under zoneless change detection that machinery is Angular's own no-op and a signal you set in a handler repaints the view. The one thing to know when reading the grid's DOM from Angular: the grid paints on its own schedule, not Angular's, so measure a cell in a grid event, not in ngAfterViewInit.

OnPush is safe everywhere. None of these components asks its parent to re-render: each owns one element, builds one instance in afterNextRender and pushes changed inputs into it from ngOnChanges. A host on OnPush that never re-renders still gets a fully live grid, because the grid is not rendered by Angular.

Inputs are diffed by identity, and never rebuild the instance. A changed input reaches the viewer that is already on screen - scroll position, selection, expansion and any open editor intact. Two things rebuild rather than update: the grid a viewer is bound to, and an input it cannot exist without. An input a viewer has no live setter for is named once in a warning rather than silently dropped. And because the comparison is Object.is, an inline [config]="{ rows: rows }" is a new object on every pass: hold it in a field or a signal.

Cleanup is the component's. ngOnDestroy detaches from the router, withdraws the grid from the registry and destroys the instance - in that order. An @if that closes and opens again leaves exactly one instance alive, and destroying the application leaves no instance, interval or listener behind. That is asserted with counters in a real browser, against the linked package, in test/angular-package-browser.test.js.

Angular 17 and up, browser only. The library is compiled partially, so your own Angular version compiles it: its declarations need a linker no newer than 14, and its peer range is >=17. Nothing is created on the server - isPlatformBrowser guards every build and afterNextRender does not run there - so a server-rendered page emits the empty host element and the grid is built on hydration. Angular Universal is not otherwise supported.

modules/angular is deprecated. The old bundle still works where it always worked - a page with @angular/compiler loaded - and it now says so once, and fails with a [lattice] message naming this package when it finds a real Angular with no JIT compiler, instead of leaving you with Angular's own. In 1.65 it also gained the fix that <div [latticeGrid]="config"> binds the configuration through the directive's selector, as its documentation always said it did. It will be removed in a later release; move to @toclocoinc/lattice-grid/angular, which covers every viewer rather than the grid alone and needs no second install.

// your-lattice.js - the one place that knows your house defaults
import { createGrid as baseCreateGrid } from '@toclocoinc/lattice-grid';

export function createGrid(element, config) {
  return baseCreateGrid(element, { theme: 'house', density: 'compact', ...config });
}

// everywhere else
import { createGrid } from './your-lattice.js';

const { createHeadlessGrid, defaults } = await import('../packages/core/src/index.js');

// One place says what every grid in this application starts from.
defaults({ rowKey: 'id', selection: 'multiple' });

// This grid says nothing about rowKey, so the house value applies.
const a = createHeadlessGrid({
  columns: [{ field: 'id' }, { field: 'name' }],
  rows: [{ id: 'a1', name: 'Ada' }],
});
const house = a.rows.byKey('a1').data.name;

// This one names its own rowKey. The grid's own config always wins.
const b = createHeadlessGrid({
  rowKey: 'sku',
  columns: [{ field: 'sku' }],
  rows: [{ sku: 's9', id: 'ignored' }],
});
const own = b.rows.byKey('s9') !== undefined && b.rows.byKey('ignored') === undefined;

a.destroy();
b.destroy();
defaults(null);                // clear: grids built after this are unaffected
return `${house}; own-key ${own}; cleared ${JSON.stringify(defaults())}`;

<lattice-grid> web component

A self-contained module bundle that registers a custom element on import. One script, one tag, no build step, for Rails, Django, Laravel or any page without a bundler. Load this or lattice-grid.esm.js, not both: the module carries the grid with it.

<link rel="stylesheet" href="dist/lattice-grid.min.css">
<script type="module" src="dist/modules/webcomponent.esm.min.js"></script>

<lattice-grid row-key="id"
  columns='[{"field":"id"},{"field":"city"}]'
  rows='[{"id":"A","city":"Leeds"}]'></lattice-grid>

Events are re-dispatched as CustomEvents named lattice- plus the grid name with colons hyphenated: cell:changed becomes lattice-cell-changed. The payload is on event.detail. The prefix avoids colliding with platform events, the grid emits one called scroll.

Web Components: every viewer, not only the grid

Since 1.66 the same bundle registers one element per viewer, so a page without a bundler gets the KPI panel, a chart, the board, the Gantt, the dashboard layout, the tab strip and the Data Router as tags. The grid is already registered on import; defineLatticeElements registers the rest from the module factories the page has imported, because nothing is imported by this module - a page that draws no charts never loads the charts bundle.

// Every tag this package can register, under the default prefix.
const { ELEMENT_TAGS } = await import('../packages/modules/webcomponent/elements.js');
return Object.keys(ELEMENT_TAGS).length;

<script type="module">
  import { createKPI } from './dist/modules/kpi.esm.js';
  import { createChart } from './dist/modules/charts.esm.js';
  import { defineLatticeElements } from './dist/modules/webcomponent.esm.js';
  defineLatticeElements({ createKPI, createChart });
</script>

<lattice-grid name="quakes" row-key="id"></lattice-grid>
<lattice-kpi   grid-name="quakes"></lattice-kpi>
<lattice-chart grid-name="quakes" type="bar" x="place" y="mag"></lattice-chart>

Attributes for scalars, properties for structures. An attribute is a string, so columns, rows, tiles, tasks, windows and a geometry pack are properties. Scalars work as either: an empty attribute is true, true/false are booleans, a finite number is a number, a value starting [ or { is JSON, and anything else is the string - so use the property when the type matters. On the viewer elements a hyphenated attribute reaches the camelCase key (column-property → columnProperty). Every configuration key has a real property, including one no table here names: assign it and the element adopts it. <lattice-grid> keeps its own attribute table above - each of those is a property too (el.theme, el.rowKey) - and takes everything outside it through config.

Upgrade order. A property assigned before the element upgrades is honoured. Set your configuration before the element connects - document.createElement, assign, then append - so the viewer is built once with everything it needs rather than built empty and reconfigured; in markup, use the JSON attribute forms. Cleanup is on disconnect, deferred by a microtask so moving an element in the DOM keeps its instance rather than rebuilding it. SSR: every element owns a real DOM node, so nothing is built until it is connected in a browser; a server render emits the empty tag and no more.

Events. Instance events are CustomEvents named lattice- plus the event name with colons hyphenated (card:move → lattice-card-move); the prefix is load-bearing, because the grid emits scroll and a chart emits click. The lifecycle events are this adapter's own and are unprefixed: grid-ready / grid-destroyed on the grid and ready / destroyed on every viewer, each carrying the instance in detail. The instance is also on el.grid / el.instance.

Inside a shadow root

The elements are light DOM, deliberately. A host that puts them inside a shadow root of its own is a different matter: the theme, each module's injected stylesheet and the grid's generated one all live in document.head and none of them crosses a shadow boundary, so a grid in there used to render structurally perfect and completely unstyled. Every element now calls adoptLatticeStyles on its own root when that root is a shadow root, mirroring each sheet as a constructable CSSStyleSheet and keeping it level as the grid compiles new classes and as a module injects its own. A host that manages its own adoptedStyleSheets can take the sheets directly with latticeStyleSheets(); lattice-styles="off" on an element opts out. A stylesheet that cannot be read as text - a cross-origin <link>, or one carrying @import - is cloned into the root as a <link> instead.

const root = host.attachShadow({ mode: 'open' });
adoptLatticeStyles(root);
root.append(document.createElement('lattice-grid'));

dhtmlx Grid compatibility wrapper

A Grid class shaped like dhtmlx's own dhx.Grid (Suite 5+), backed by a real Lattice grid. Covers column definitions, .data, .selection, .history, .export.csv/.xlsx, and a name-mapped subset of .events: see the guide for exactly what is and is not covered. Not the classic pre-Suite-5 dhtmlXGridObject.

import { Grid } from './dist/modules/dhtmlx-compat.esm.min.js';

const grid = new Grid(container, {
  columns: [{ id: 'name', header: [{ text: 'Name' }], sortable: true }],
  data: rows,
});
grid.data.serialize(); // every row's data, in source order

Which dhtmlx keys are translated

A key outside these lists is not silently dropped: the wrapper names it through warnOnce at construction, so a migration is told what did not come across rather than discovering it later.

Declarative init, hydration & state

Core-level primitives, usable with or without any framework adapter or the htmx module below. An element built by createGrid is discoverable from itself: element.__lattice holds the live instance, cleared on destroy().

htmx integration

One file. modules/htmx re-exports createGrid, autoInit, hydrateTable, readTable, serialiseState and restoreState alongside its own exports below, so a page using htmx integration never also loads the base bundle: that would mean two independent copies of the whole engine on one page. Registers on import: builds grids from [data-lattice-grid] elements or server-rendered <table>s, tears them down before htmx detaches a swapped-out subtree, and rebuilds them in newly-loaded content. driveServerMode/driveInfiniteScroll drive sort, filter and infinite scroll over plain htmx requests; driveOobUpdates applies out-of-band row updates in place. See the guide for the full request-lifecycle wiring and why infinite scroll uses two triggers.

import { autoInit, driveServerMode, driveInfiniteScroll } from './dist/modules/htmx.esm.min.js';

autoInit(document); // builds every [data-lattice-grid] under it

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

Framework adapters

The component wrappers each framework package exports.

LatticeGridHandle

The live instance a `<LatticeGrid>` ref exposes; `null` before mount.

LatticeViewerHandle

The live instance a viewer component's ref exposes; `null` before mount.

LatticeViewerCommonProps

What every viewer component takes beyond its own configuration: the grid it binds to, which published grid to take when that is left off, the lifecycle callbacks, and the host-element props.

Properties

Methods

Events

No events.

LatticeTabSpec

One tab of a `<LatticeTabs>`; `content` makes it React's rather than the module's.

LatticeVueGridExposed

What a `<LatticeGrid>` template ref exposes; `grid()` is null before mount.

LatticeVueViewerExposed

What a viewer's template ref exposes; `instance()` is null before mount.

LatticeVueTabSpec

One tab of a `<LatticeTabs>`; a slot named for its `id` makes it Vue's.

LatticeVueGridRegistry

Where grids publish themselves so the viewers around them can find one.

Properties

Methods

Events

No events.

LatticeVueRouterHandle

The Data Router handle a `provideLatticeRouter` puts in scope.

Properties

Methods

Events

No events.

LatticeGridElement

`<lattice-grid>`. Structures are properties, scalars are the attributes in the table above, and `config` merges anything without an attribute of its own. Instance events arrive as `CustomEvent`s named `lattice-` plus the event name with colons hyphenated; `grid-ready` and `grid-destroyed` are this adapter's own and carry {@link LatticeGridEventDetail}.

Properties

Methods

No methods.

Events

No events.

LatticeViewerElement

What every viewer element carries.

Properties

Methods

No methods.

Events

No events.

LatticeKPIElement

`<lattice-kpi>`. Grid-bound by default, and it **waits** for its grid rather than mounting empty; give it `rows` for a standalone panel.

LatticeChartElement

`<lattice-chart>`. Always drawn from a grid, so it waits for one.

LatticeKanbanElement

`<lattice-kanban>`. Grid-bound like the KPI panel; give it `rows` to stand alone.

LatticeGanttElement

`<lattice-gantt>`.

LatticeLayoutElement

`<lattice-layout>`.

LatticeTabsElement

`<lattice-tabs>`. A tab's content is a `<template data-tab="‹id›">` child, cloned into the panel the module creates for it; a tab with no template is left to the module.

LatticeRouterElement

`<lattice-router>`. Owns a Data Router for the life of the element, built by the first `<lattice-grid route="…">` beneath it.

Properties

Methods

No methods.

Events

No events.