gridcn2.0.0
Columns

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.

Name
Email
Role
Joined
Age
Bio (double-click edge to autosize)
Score
Silent Tiger
user0@example.com
Viewer
2023-07-05
63
Silent Tiger has been a viewer since 2023-07-05.
4
Quick Lion
user1@example.com
Viewer
2021-04-03
67
Quick Lion has been a viewer since 2021-04-03.
89
Swift Wolf
user2@example.com
Manager
2020-10-27
40
Swift Wolf has been a manager since 2020-10-27.
80
Eager Lion
user3@example.com
User
2022-10-08
50
Eager Lion has been a user since 2022-10-08.
51
Eager Tiger
user4@example.com
Viewer
2024-10-07
45
Eager Tiger has been a viewer since 2024-10-07.
83
Silent Wolf
user5@example.com
User
2020-06-01
24
Silent Wolf has been a user since 2020-06-01.
15
Swift Lion
user6@example.com
Viewer
2022-10-18
34
Swift Lion has been a viewer since 2022-10-18.
62
Eager Lion
user7@example.com
Manager
2021-10-07
21
Eager Lion has been a manager since 2021-10-07.
42
Eager Eagle
user8@example.com
Editor
2024-06-11
25
Eager Eagle has been a editor since 2024-06-11.
35
Bold Tiger
user9@example.com
Editor
2024-03-20
19
Bold Tiger has been a editor since 2024-03-20.
52
Bold Bear
user10@example.com
User
2020-04-16
42
Bold Bear has been a user since 2020-04-16.
28
Swift Wolf
user11@example.com
Manager
2022-08-04
47
Swift Wolf has been a manager since 2022-08-04.
9

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

FieldTypeDefault
pin"start" | "end"none
pinnablebooleantrue
reorderablebooleantrue
PropTypeDefault
enableColumnPinningbooleantrue
enableColumnReorderbooleantrue

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.

On this page