JavaScript Data Grid Developer Guide

Why it matters to you: sorting a column is a sort over one contiguous array of numbers, not a walk over a hundred thousand objects. Filtering produces a bitmask rather than a new array of rows. Both stay fast at sizes where the row-object approach has already given up, and neither allocates much, so the browser is not collecting garbage while the user is scrolling. How it works goes through the layout in full, including what it costs and where it does not help.

Change a sort and the filter stage is not recomputed: its inputs did not change. Edit a cell in a column nobody sorts, filters or groups on and none of the first five run; only the totals move. This is why a grid that is heavily filtered and grouped still feels immediate when you type in a cell.

A large share of enterprise line-of-business frontends are built without a bundler, and they are usually treated as second-class by grid vendors. Here the script tag is the first example in the documentation, not an appendix.

On rowKey: it names the field that identifies a row. Set it if you have one. Without it the grid assigns keys per row object, which is enough for sorting, filtering, selection and copying within a session, but not across a reload, because new objects are new rows. Change tracking, streaming dedupe, selection persistence and remote reload all want a real key, and the grid warns once, naming them.

You pass the framework in. Every adapter is a factory taking the framework and createGrid, rather than importing either. Lattice ships zero dependencies and the bundler rejects bare specifiers outright, so an adapter could not import React from 'react' even if it wanted to. The same choice keeps each bundle small: the bundler inlines whatever it can resolve, so an adapter that imported the grid would carry a second copy of it. Passing both in leaves each adapter a few kilobytes of glue, and means the adapter cannot disagree with the grid version you already loaded.

Hold your props steady. Change detection is reference equality, because deep-comparing a million-row array on every render would cost more than the reload it avoids. Build columns once outside the component, or memoise it; a fresh array literal on each render tells the grid the columns changed and it will rebuild them. Rows are the same: hand back a new array when the data actually changes, not before.

StrictMode is handled. React 18 deliberately mounts, unmounts and mounts again in development; the effect cleanup destroys the first grid, so the second starts clean and nothing leaks.

Every viewer is a component now. Before 1.63 the adapter wrapped createGrid and nothing else, so a React application wrote its own useEffect for the KPI panel, for each chart, for the board, for the Gantt - and its own tab strip, because the tabs module builds its tabs' grids itself and a grid built that way is not a component. createLatticeKPI, createLatticeChart, createLatticeKanban, createLatticeCalendar, createLatticeGantt, createLatticeScheduler, createLatticeShell, createLatticeForm, createLatticeLayout, createLatticeTabs and createLatticeDesigner each return one component; createLatticeViewer is the generic behind them, for anything not yet named, and createViewerController is the framework-free lifecycle underneath. createLatticeDesigner is the designer's own component: its state is controlled when the host passes it, and it is driven through the framework-free createDesignerController, the same lifecycle shape the viewer table uses.

A viewer finds its grid through context, not a ref. A KPI panel and a chart are built against a grid instance, and that instance does not exist until after the first render. Writing to a ref re-renders nobody, so a sibling never learns the grid arrived. createLatticeGridContext returns { LatticeGridProvider, useLatticeGrid }: a grid publishes itself under its name, a viewer takes it by gridName, and the viewer is built the moment it appears. A page with one grid names nothing.

A tab's content is yours. createLatticeTabs keeps the module's tablist semantics, keyboard handling, lazy first mount and live badges, and renders each tab's React content into the module's own panel element through a portal - so a tab's grid is a real <LatticeGrid> with props, a ref and the surrounding context. A tab with no content is left to the module, so both kinds mix on one strip.

The router is owned by a hook. createLatticeRouter returns useLatticeRouter, which creates the router in an effect and destroys it in that effect's cleanup - never in a useState initialiser, which React calls more than once by design and whose discarded copy is never destroyed. It returns null on the first render and the router on the second. <LatticeGrid route="…"> attaches to whichever router LatticeRouterProvider published, and detaches before the grid is destroyed so the router never holds a dead grid.

A live feed needs no ref. rowUpdates is a keyed diff handed to grid.rows.apply() whenever the object's identity changes. predicates maps { name: fn } to grid.filters.where(name, fn), which composes with whatever filter the reader set - unlike the filters prop, which replaces the whole tree.

What is a live prop is declared, not guessed. The grid takes any changed configuration key through one call; no other viewer does. So each viewer lists the props it can take while running (VIEWER_APPLY) and everything else is mount-time configuration. A mount-time prop that changes is neither ignored nor silently remounted: it is named once, with the remedy - a key that changes when you want the rebuild, or the ref. VIEWER_EVENTS and viewerHandlerName are the matching event surface (card:move becomes onCardMove), and DEFAULT_GRID_NAME is the name a grid publishes under when you choose none.

React 18 and 19, client only. Nothing uses an API added in 19 or removed in 19. Every component owns a real DOM element, so there is no SSR and no React Server Component support.

One import changes; the page does not. createLatticeDataGrid returns a component that takes the free-tier <DataGrid> props and maps each onto the grid: rows, columns, getRowId, loading, density, checkboxSelection, disableRowSelectionOnClick, editMode, the controlled models sortModel, filterModel, rowSelectionModel, columnVisibilityModel and paginationModel with onSortModelChange, onFilterModelChange, onRowSelectionModelChange, onColumnVisibilityModelChange and onPaginationModelChange, pageSizeOptions, the events onRowClick, onCellClick, onCellDoubleClick, onCellEditStop, onRowEditStop, onColumnResize, onColumnOrderChange, onCellModesModelChange, onRowModesModelChange and onDataSourceError, plus apiRef, slots (the toolbar) with showToolbar, className and style. A column definition's field, headerName, width, flex, type, valueGetter, valueFormatter, renderCell, editable, sortable and filterable are mapped, with MUI's argument order. apiRef.current carries getSelectedRows, setSortModel, setFilterModel, scrollToIndexes, exportDataAsCsv and updateRows.

Anything else is refused by name, never guessed at. A prop the component does not map - sx, initialState, a Pro prop such as rowGroupingModel, an unknown column key - prints one react:mui-prop-unsupported:<prop> warning and is ignored. A filter model holding one operator it cannot translate is not applied at all, because applying the rest would show rows nobody asked for.

Paging is MUI's only over a memory source. MUI pages rows the browser already holds. Give the component a Lattice source (a pushdown engine, a paged endpoint) and the page belongs to the source: the three paging props are refused by name and the rows are left as the source delivers them. createDataGridController is the framework-free half underneath, for driving the same translation without React. The component is React-only by design: it is a migration path off a data-grid package, which the other frameworks do not need.

Events are re-emitted under dashed names: cell:changed becomes @cell-changed, because a colon in a Vue template is directive syntax and cannot be bound. Every event in the table below is declared in emits.

Every viewer is a component now. Before 1.66 the adapter wrapped createGrid and nothing else, so a Vue application wrote its own onMounted/onBeforeUnmount pair for the KPI panel, for each chart, for the board, for the Gantt - and its own tab strip, because the tabs module builds its tabs' grids itself and a grid built that way is not a component. createLatticeKPI, createLatticeChart, createLatticeKanban, createLatticeCalendar, createLatticeGantt, createLatticeScheduler, createLatticeShell, createLatticeForm, createLatticeLayout, createLatticeTabs and createLatticeDesigner each return one component definition; createLatticeViewer is the generic behind them, for anything not yet named, and createViewerController is the framework-free lifecycle underneath. Everything is built with defineComponent and render functions, so no template compiler is needed in your build and vue.runtime.* is enough. The floor is Vue 3.3, and Vue 2 is not supported.

A viewer finds its grid through provide, not a template ref. A KPI panel and a chart are built against a grid instance, and that instance does not exist until after the first render. Assigning to a template ref re-renders nobody, so a sibling never learns the grid arrived. createLatticeGridContext returns { LatticeGridProvider, provideLatticeGrids, useLatticeGrid }: call provideLatticeGrids() in a parent's setup (or wrap the subtree in <LatticeGridProvider>), a grid publishes itself under its name, a viewer takes it by grid-name, and the viewer is built the moment it appears. A page with one grid names nothing.

A tab's content is a slot. createLatticeTabs keeps the module's tablist semantics, keyboard handling, lazy first mount and live badges, and renders each tab's named slot - <template #all> for a tab with id: 'all', or <template #tab-all> - into the module's own panel element through a <Teleport>. So a tab's grid is a real component with props, a ref and the surrounding provides. A tab with no slot is left to the module, so both kinds mix on one strip.

The router belongs to a scope. createLatticeRouter returns provideLatticeRouter, which you call in a component's setup. The router is built lazily by the first grid beneath it that names a route, and destroyed when that component's scope is disposed - so it lives exactly as long as the page that owns it. The configuration is read once: rebuilding would drop every attached grid and every row held. A grid detaches before it is destroyed, so the router never holds a dead grid, and useLatticeRouter() hands any descendant the same handle.

A live feed needs no ref. row-updates is a keyed diff handed to grid.rows.apply() whenever the object's identity changes. predicates maps { name: fn } to grid.filters.where(name, fn), which composes with whatever filter the reader set - unlike the filters prop, which replaces the whole tree.

What is a live prop is declared, not guessed. The grid takes any changed configuration key through one call; no other viewer does. So each viewer lists the props it can take while running (VIEWER_APPLY) and everything else is mount-time configuration. A mount-time prop that changes is neither ignored nor silently remounted: it is named once, with the remedy - a :key that changes when you want the rebuild, or the exposed instance. VIEWER_EVENTS and viewerHandlerName are the matching event surface (card:move, which a template binds as @card-move), and DEFAULT_GRID_NAME is the name a grid publishes under when you choose none.

Reactivity: shallow, and measured on a grid event. Hold a large rows array in a shallowRef and assign a new array when it changes; a plain ref makes every row object a reactive proxy, which the grid neither needs nor wants. Nothing in the adapter uses a { deep: true } watcher, for the same reason - one watcher per prop, compared with Object.is. And the grid paints on its own schedule rather than Vue's, so nextTick() means "Vue has patched", not "the grid has painted": measure in @render-done or @rows-changed.

Client only. Every component owns a real DOM element and builds nothing before onMounted, so a server render emits the empty host: there is no SSR or Nuxt server-side support. 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.

Since 1.66, components too. An action cannot express what the other adapters express - it takes a node and a value, so it has no children, no snippets and no context - so the package also ships a Svelte 5 component per viewer as .svelte source at @toclocoinc/lattice-grid/svelte/*.svelte, compiled by your own toolchain, with svelte as an optional peer dependency. Wrap a subtree in GridProvider.svelte and a grid publishes itself under its name for a chart or a KPI panel beside it to find; wrap one in Router.svelte and a grid that names a route is attached to a Data Router built with the first of them. Both are built from exported helpers you can call yourself - createGridRegistry() returns the registry a provider puts in context, and createRouterHandle({ createDataRouter }) returns the router handle, built on first use and destroyed with the component that owns it. See Svelte 5: components you compile. The action below is unchanged and still supported.

An action, not a component. Svelte's action contract is { update, destroy } over a node the caller already owns, which is exactly the shape of the work: create, push changes, tear down. A component wrapper would add an element and a props layer to arrive back at the same three calls. It is also the only adapter here that needs nothing but createGrid, since an action is a plain function with no framework runtime behind it. Grid events arrive as CustomEvents on the node, with the grid event as detail. If you want a component, four lines around this gets you one.

Reaching the grid. The action's return value is Svelte's { update, destroy } and cannot carry the instance, so - at parity with React's ref.current.grid and Vue's expose({ grid }) - there are two documented routes to the same object the vanilla examples use, for charts, statistics and imperative pivot. Pass an onGrid callback in the action params and it is called once with the live grid the moment it is created (synchronously, before the first render); it is consumed by the adapter and never reaches the grid config. Or read it off the ready event, whose detail carries { grid } alongside the event's own fields - ready fires a turn later, so use onGrid when you need it up front.

What the adapters do not do. They add no features and wrap no API: the grid instance is the same object the vanilla examples use, and anything without a prop is reached through it directly - via the ref in React, expose in Vue, or onGrid / the ready event in Svelte, as the table above shows. Nothing is proxied, so nothing can lag behind the grid.

Do not load it alongside createGrid in the same page. You would get two independent copies of the grid, and the cost is not the download, it is that each copy keeps its own registries. A renderer, editor, data type or variant registered through one is invisible to the other, and a licence key validated in one is not validated in the other. Nothing errors; the custom renderer you registered simply never appears.

Pick one route per application. The other three adapters take createGrid as an argument and so share whatever copy you already loaded, and can be mixed with direct API use freely.

value and text are different questions and the difference bites people. A currency column's value is 1234.5; its text is £1,234.50. Sorting and filtering use the value. Copying, exporting and searching use the text, because that is what the user can see and what they typed against.

origin tells you where a change came from: 'user', 'api', 'init', 'undo'. It is what stops a feedback loop when you persist changes: a handler that writes to a server on cell:changed should usually ignore its own 'undo' traffic, or at least know that is what it is looking at.

A grid mounted where it has no rendered box paints only a handful of rows, not the whole dataset - by design, not as a bug. The visible row window is computed from the container's own height; a container that is detached from the document, or sits under a display: none ancestor, measures zero, and the virtualiser falls back to a small band around the top of the data (the overscan margin, five rows with the default configuration) rather than nothing at all. A harness that builds a grid off in a hidden or unattached container and then asserts on what is visible reads far fewer rows than it loaded and looks broken; giving the container a real, measured box before asserting is what fixes it. Note that this is about the container having no computed size, not about being visually off-screen: a container positioned outside the browser's visible area with real, explicit dimensions (for example position: fixed; left: -9999px with a width and height) still gets a real box and renders fully.

The in-repo test DOM (testdom.js) is a stub, not a browser, and says so in its own header comment. It implements exactly the surface the renderer touches - element creation, attributes, classList, style, children, textContent, event dispatch, injected geometry, and shims for ResizeObserver and requestAnimationFrame - which is enough to drive the renderer's logic in Node for most of the suite. It does not compute a cascade or a layout, so a class or style change that a stylesheet then overrides, or a box that depends on CSS rather than on the geometry a test injected, is invisible to it; those need the real-browser tests (test/*-browser.test.js) that drive an actual headless Chrome instead. It also does not model real focus semantics - its focus() simply records which element is "focused" with no check for visibility, tab order or focusability. Since, classList.add does throw on a token containing a space, the same InvalidCharacterError a real DOMTokenList throws, closing the specific gap where a two-word class name passed every headless test and then blanked a real page.