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.
| Prop | Purpose | Default |
|---|---|---|
columnLayout | The layout that your code controls. Each part has its own control | none |
defaultColumnLayout | The layout, seeded once at mount | none |
onColumnLayoutChange | Fires with the full layout after a committed change | none |
onColumnResizing | Fires on each live width write during a resize drag | none |
onRenderedRowsChange | Fires with the range of rendered view rows | none |
onColumnLayoutChange
The callback receives a ColumnLayout:
| Field | Meaning |
|---|---|
widths | Width in pixels by column id, for the columns with a width set by the user |
order | The complete column id order, not only the moved column |
pins | "start" or "end" by column id |
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, orautosizeOnMount, - a width reset,
- a reorder drop,
- a pin or an unpin,
- a show or a hide,
- a
setColumnLayoutcall.
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
orderlacks. - 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.