Save a column layout
Store the widths, order, pins, and hidden columns of a user, and restore them on the next visit.
A user resizes, reorders, pins, and hides columns. Store that layout when it changes, and give it back to the grid on the next visit. onColumnLayoutChange reports the layout, and columnLayout or defaultColumnLayout restores it.
A ColumnLayout holds four parts:
widthsmaps column ids to px, for resized columns only.orderlists the ids of all columns in column order, hidden ones included. Pins do not move a column in this list.pinsmaps column ids to"start"or"end".hiddenlists the ids of hidden columns.
| Prop | Type | Default |
|---|---|---|
defaultColumnLayout | Partial<ColumnLayout> | none |
columnLayout | Partial<ColumnLayout> | none |
onColumnLayoutChange | (next: ColumnLayout) => void | none |
Steps
- Pass
onColumnLayoutChange. It receives aColumnLayoutsnapshot after every committed change. Store the snapshot. - Load the stored snapshot on the next visit.
- Give it to the grid. If the first render already has the layout, for example from a cookie, pass it as
defaultColumnLayout. The grid reads that prop once, at mount. - If the layout loads after the first render, pass it as
columnLayout.
localStorage does not exist on the server, so a layout from it is unknown at the first render in Next.js. Load it in an effect. The grid shows the default layout first, then the saved one:
"use client";
import { useEffect, useState } from "react";
import {
DataGrid,
defineColumns,
type ColumnLayout,
} from "@/components/data-grid/data-grid";
type Row = { id: string; name: string; email: string };
const rows: Row[] = [{ id: "1", name: "Ada", email: "ada@example.com" }];
const columns = defineColumns<Row>()([
{ id: "name", header: "Name", accessorKey: "name" },
{ id: "email", header: "Email", accessorKey: "email" },
]);
const LAYOUT_KEY = "my-grid-layout";
export function SavedLayoutGrid() {
const [layout, setLayout] = useState<Partial<ColumnLayout>>();
useEffect(() => {
const saved = localStorage.getItem(LAYOUT_KEY);
if (!saved) return;
try {
const parsed: unknown = JSON.parse(saved);
if (parsed && typeof parsed === "object") {
setLayout(parsed as Partial<ColumnLayout>);
}
} catch {
localStorage.removeItem(LAYOUT_KEY);
}
}, []);
return (
<DataGrid
defaultData={rows}
columns={columns}
className="h-80"
columnLayout={layout}
onColumnLayoutChange={(next) => {
setLayout(next);
localStorage.setItem(LAYOUT_KEY, JSON.stringify(next));
}}
/>
);
}Result
The grid restores the saved widths, order, pins, and hidden columns after a reload. The layout stays in the browser in every data mode. The grid sends no part of it to fetchRows or onSave.
onColumnLayoutChange fires once for each committed change. That covers a resize release, an autosize, a width reset, a reorder drop, a pin or unpin, and a hide or show. It does not fire on each frame of a drag, and it does not fire for a change that alters nothing. Column and viewport events lists the payloads.
Each part of columnLayout replaces that part. An omitted part stays under the control of the grid. So columnLayout={{ widths }} controls widths, and a user reorder survives.
A user change applies at once. The grid applies columnLayout again only when the prop is a new object that differs from the current layout. Keep the object stable, for example in state, and store each onColumnLayoutChange snapshot in it. actions.setColumnLayout(parts) applies a partial layout from code as one change. actions.resetColumnLayout() restores the widths, order, pins, and hidden columns of the column definitions as one change.
defaultColumnLayout also takes a function. It runs once on the client after mount, never on the server, so it can read localStorage without a hydration mismatch.
The grid cleans a layout before it applies it:
- It drops ids that match no column.
- It adds columns that
orderdoes not list after the listed ones, incolumnsorder. Ahidden: truecolumn thatorderdoes not list stays hidden. - It clamps each width to
minWidthandmaxWidth. - It ignores the pins of a
pinnable: falsecolumn. That column keeps thepinof its definition. For every other column, whenpinsis present, a column that it does not list loses its ownpin. - A part with the wrong shape resets that part to the column definitions: no stored widths, the
columnsorder, and thehiddenflags. A layout that isnullor not an object does nothing.
To keep order and hidden columns in a shareable link, use the URL state add-on.
Related
- Column visibility
- Column sizing
- Column order and pinning
- Column layout example
- Remember filters and layout: keep filters and layout across visits