Performance guidance
Keep a 100,000-row grid smooth. See what the grid does for you, which props to keep stable, and how to check scroll speed.
Why does a grid with 100,000 rows scroll smoothly, and what slows it down? The grid draws only the rows in view and skips work for rows that did not change. Your code keeps the second part working. A new columns array or data array on every render makes every row in view render again.
What the grid does for you
- It mounts only the rows and columns in view. Virtualization explains the model.
- A scroll step of one row keeps the DOM node of every row that stays in view. The row keeps its place in the layout, so the browser does not lay it out again.
- Row hover is a
data-hoveredattribute on the row under the pointer. A:hoverrule makes Chrome restyle the rows that move under a resting pointer on every scroll tick. The attribute moves only between scroll bursts. - The grid reads the row under the pointer again after a scroll settles and after the view changes.
- If a horizontal scroll changes the rendered columns, marker cells do not render again.
- A selection move renders again only the cells whose own state changes.
- An editor mounts only in the cell that you edit.
- A live update with
reorder: "immediate"moves only the patched rows. A batch of more than 256 rows, or a sort or filter change in the same tick, rebuilds the whole order. A feed of many small ticks per second takesreorder: "frame", which re-places the patched rows once per animation frame. See Stream updates.
Keep references stable
A row skips rendering while its props keep the same identity. If the component that renders the grid renders often, define these values at module level or memoize them:
columnsdatain a controlled grid- Render props such as
renderMarker,renderMarkerHeader, andrenderHeaderCell(onDataGridHeader)
This component builds a new columns array on every render, so every row renders again:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Task = { id: string; title: string };
export function SlowTasks({ tasks }: { tasks: Task[] }) {
const columns = defineColumns<Task>()([
{ id: "title", header: "Title", accessorKey: "title" },
] as const);
return <DataGrid data={tasks} columns={columns} className="h-96" />;
}This component defines columns once at module level, so a row renders again only when its own data changes:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Task = { id: string; title: string };
const columns = defineColumns<Task>()([
{ id: "title", header: "Title", accessorKey: "title" },
] as const);
export function FastTasks({ tasks }: { tasks: Task[] }) {
return <DataGrid data={tasks} columns={columns} className="h-96" />;
}In a controlled grid, store the array that onDataChange passes as it is. A copy, map, or filter makes the grid rebuild its row id map and its view on every change.
If an identity changes between renders, a development build logs a warning:
| Value | The warning appears when |
|---|---|
columns | A new array holds the same columns as the old array. |
data | A new array has the same length and no new row. Controlled grids only. |
A plugin Overlay or Mount | The component identity differs. The overlay remounts and loses its state. |
An inline getRowId function costs nothing. If the new function returns the same ids as the old one for the first and the last row, the grid keeps the old function. To change getRowId, pass it together with a new data array: a new array always takes the new function.
The columns warning reads columns array identity changed since the last render. The data warning reads data array identity changed with no row changes.
getRowClassName and getCellClassName can be inline functions. Rows and cells re-render only when the function returns different classes for the rendered rows.
Custom cells render for each row that scrolls into view. Keep renderCell cheap.
Tests that guard scroll speed
Real-Chromium suites guard the scroll path. They check that no row is missing after random scrollbar drags settle and after a sequence of large jumps. They compare a scroll of 800 px per frame, which replaces every rendered row, with a scroll of 8 px per frame. They cap long tasks during a fling, run a sequence of jumps, and count renders of marker cells and rows. Run the benchmark is the page for running them.
Load less data
Virtualization limits what the grid draws, not what your page holds. If the page cannot load every row, fetch rows as the user scrolls with scroll mode. One browser limit caps the row count of a single grid. Row limits lists it.
Related
- Virtualization: what the grid mounts and why
- Row limits: the browser limits on row count
- Run the benchmark: measure scroll speed yourself
- Bundle size: what the core and each add-on add
- Load rows while scrolling: fetch rows on demand