gridcn2.0.0
Events and state

Column and viewport events

Save and restore the column layout, read live widths during a resize, and learn which rows the grid has rendered.

Three callbacks report the shape of the grid. onColumnLayoutChange reports the column widths, order, pins, and hidden columns. onColumnResizing reports live widths. onRenderedRowsChange reports the rendered rows.

PropPurposeDefault
columnLayoutThe layout that your code controls. Each part has its own controlnone
defaultColumnLayoutThe layout, seeded once at mountnone
onColumnLayoutChangeFires with the full layout after a committed changenone
onColumnResizingFires on each live width write during a resize dragnone
onRenderedRowsChangeFires with the range of rendered view rowsnone

onColumnLayoutChange

The callback receives a ColumnLayout:

FieldMeaning
widthsWidth in pixels by column id, for the columns with a width set by the user
orderThe complete column id order, not only the moved column
pins"start" or "end" by column id
hiddenThe ids of the hidden columns

It fires once per committed change. These changes commit:

  • the release of a resize drag, and an autosize from a double-click, the header menu, autosizeColumns, or autosizeOnMount,
  • a width reset,
  • a reorder drop,
  • a pin or an unpin,
  • a show or a hide,
  • a setColumnLayout call.

It never fires per drag frame. If the layout does not change, it does not fire.

The callback runs after the grid writes the layout. If it throws, the layout stays, and the grid rethrows the error after the other callbacks of the change ran. onColumnResizing follows the same rule. See Callback timing and errors.

Save and restore

defaultColumnLayout seeds the widths, order, pins, and hidden columns once at mount. It layers over the column definitions, so a saved width beats the width of a column. The grid ignores later changes to the value. It cleans the saved layout:

  • It drops unknown column ids and clamps widths.
  • It ignores pins on columns with pinnable: false.
  • It appends columns that the saved order lacks.
  • It moves the columns of a group next to each other again.

The sample reads the saved layout and writes each change back:

import {
  DataGrid,
  defineColumns,
  type ColumnLayout,
} from "@/components/data-grid/data-grid";

type Row = { id: string; name: string };

const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

function readSavedLayout(): Partial<ColumnLayout> | undefined {
  try {
    const text = localStorage.getItem("layout");
    return text ? (JSON.parse(text) as Partial<ColumnLayout>) : undefined;
  } catch {
    return undefined;
  }
}

function Grid({ rows }: { rows: Row[] }) {
  return (
    <DataGrid
      defaultData={rows}
      columns={columns}
      defaultColumnLayout={readSavedLayout()}
      onColumnLayoutChange={(layout) => {
        localStorage.setItem("layout", JSON.stringify(layout));
      }}
    />
  );
}

Control the layout

Pass columnLayout to control the layout. The grid applies the gesture before your code answers. A gesture writes to the grid and fires the callback at once. A value that equals the fired layout changes nothing. Any other value applies without firing the callback.

Each given part replaces that part. An omitted part keeps the current value. With columnLayout={{ widths }}, you control the widths and a reorder by the user survives.

The setColumnLayout(parts) action replaces the parts you give and commits once, like a gesture.

onColumnResizing

The callback receives { columnId, width }. It fires on every live width write during a resize drag, so it fires many times per drag. The width is already clamped to the limits of the column. Use it for a live readout. The release of the drag does not fire it. The release fires onColumnLayoutChange once.

onRenderedRowsChange

The callback receives { start, end }. It is the range of view rows that the grid has rendered. start is inclusive and end is exclusive. It fires once after the first measured render. After that, a move of the range fires it. A scroll tick inside the overscan buffer does not fire it.

The range maps to rows of data only while no client-side sort or filter is active and the grid has no pageSize. A grid with sortMode="server" and filterMode="server" keeps that mapping. useDataGridServerRows in scroll mode uses this callback to load the rows that scroll into view. In scroll mode, pass your handler to the onRenderedRowsChange option of useDataGridServerRows.

On this page