Column order and pinning
Let users drag columns into a new order and pin columns to the start or end edge so they stay in view while the grid scrolls.
A wide grid scrolls columns out of view. A pinned column stays at the start or end edge while the rest scrolls. Reorder lets users place the columns they read together next to each other. Both are on by default.
Drag a header's edge to resize (Email is fixed), double-click an edge to autosize the long Bio column, or drag a header to reorder. Hover a header for its menu (or right-click) to pin, hide, or autosize — the toolbar's columns menu restores anything hidden.
Reorder
Drag a header sideways to move its column. A drop indicator shows where the column lands. A drag that leaves the header starts the reorder. Shift+drag selects columns and does not reorder. On a touch screen, each header shows a drag handle that starts the reorder.
A column moves inside its pin zone: start-pinned, unpinned, or end-pinned. A drop in another zone changes nothing, and it does not change the pin.
To move a column without a drag, open its header menu with Shift+Alt+ArrowDown or a right-click. The context menu add-on provides it. Choose Move toward start or Move toward end. A move stays in the pin zone.
For your own control, call setColumnOrder. The column lands next to the target. The id can also name a column group, and then the whole group moves as one block:
import { useDataGridActions } from "@/components/data-grid/data-grid";
function MoveEmailFirst() {
const actions = useDataGridActions();
return (
<button onClick={() => actions.setColumnOrder("email", "name", "before")}>
Email before name
</button>
);
}Render the button inside DataGridProvider. setColumnOrder returns { ok: true }, or { ok: false, reason } when the order stays. canSetColumnOrder takes the same arguments and returns the same result without the move, for the disabled state of a button.
Two keymap actions move the active column, and both are unbound by default. This chord pair has no default binding in the grid:
import { DataGrid, defineColumns } 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" },
]);
export function MovableColumnsGrid() {
return (
<DataGrid
defaultData={rows}
columns={columns}
keymap={{
moveColumnTowardStart: ["shift+alt+ArrowLeft"],
moveColumnTowardEnd: ["shift+alt+ArrowRight"],
}}
/>
);
}reorderable: false on a column stops the drag of that column and stops drops onto it. enableColumnReorder={false} turns reorder off for the grid and makes setColumnOrder do nothing.
Pin to the start or end
pin: "start" pins a column to the start side, and pin: "end" pins it to the end side. This column stays at the start edge, so the first column is frozen:
import { defineColumns } from "@/components/data-grid/data-grid";
type Person = { id: string; name: string; email: string };
export const columns = defineColumns<Person>()([
{ id: "name", header: "Name", accessorKey: "name", pin: "start" },
{ id: "email", header: "Email", accessorKey: "email" },
]);In a left-to-right page, start means left. In a right-to-left page, start means right. pin sets the first state of a column id. A new columns array keeps the pins that setColumnPin, the context menu, and the user set, and seeds the pin of a new id.
The grid draws start-pinned columns first, then unpinned columns, then end-pinned columns. The order of columns does not change that.
At run time, users pin and unpin through the header menu of the context menu add-on. Your code calls setColumnPin(id, "start" | "end" | null). pinnable: false on a column stops every pin change for it. enableColumnPinning={false} turns off the pin items of the header menu and makes setColumnPin do nothing. setColumnLayout, columnLayout, and URL state still set pins. The pin field of a column still applies.
A soft shadow marks the edge of a pinned zone. It shows only while content scrolls out underneath. Density and small screens lists the CSS variables that style it.
Mark pinned headers
The shadow marks the edge of the zone, not each pinned header. Header and body cells of a pinned column carry data-pinned="start" or data-pinned="end". Style the marker with CSS:
[role="grid"] [role="columnheader"][data-pinned] {
border-bottom-color: var(--color-primary);
}For an icon, read the current pin from the store. The icon follows pin changes at run time:
import { Pin } from "lucide-react";
import {
DataGrid,
defineColumns,
useDataGridAllColumns,
} from "@/components/data-grid/data-grid";
type Row = { id: string; name: string };
function PinMark({ columnId }: { columnId: string }) {
const column = useDataGridAllColumns().find((entry) => entry.id === columnId);
if (!column?.pin) return null;
return <Pin className="size-3 text-muted-foreground" aria-hidden />;
}
const columns = defineColumns<Row>()([
{
id: "name",
header: (
<span className="flex items-center gap-1">
Name <PinMark columnId="name" />
</span>
),
accessorKey: "name",
pin: "start",
},
]);
export function MarkedGrid({ rows }: { rows: Row[] }) {
return <DataGrid className="h-80" defaultData={rows} columns={columns} />;
}Options
| Field | Type | Default |
|---|---|---|
pin | "start" | "end" | none |
pinnable | boolean | true |
reorderable | boolean | true |
| Prop | Type | Default |
|---|---|---|
enableColumnPinning | boolean | true |
enableColumnReorder | boolean | true |
A pin or reorder that changes the layout fires onColumnLayoutChange once. Save a column layout shows how to store it.
Server mode
Pins and order are browser state in every data mode. fetchRows and onSave get no column order. Save them with onColumnLayoutChange.