gridcn2.0.0
Performance

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-hovered attribute on the row under the pointer. A :hover rule 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 takes reorder: "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:

  • columns
  • data in a controlled grid
  • Render props such as renderMarker, renderMarkerHeader, and renderHeaderCell (on DataGridHeader)

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:

ValueThe warning appears when
columnsA new array holds the same columns as the old array.
dataA new array has the same length and no new row. Controlled grids only.
A plugin Overlay or MountThe 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.

On this page