Column headers and groups
Replace header labels with your own nodes, replace whole header cells, and put shared group headers above runs of columns.
The header row stays fixed at the top of the grid while the rows scroll under it. You need no setup for this. A header shows a label, a sort arrow, and a menu button. Set header to your own node to change the label. Use renderHeaderCell to change the whole cell content. Use columnGroups to put one shared header above several columns.
Click a group header to select its columns. Drag a group header to move the whole block, or drag a column within its group. Hide every column of a group and its header disappears.
Custom header content
header takes a string or a React node. The grid truncates a string. A node renders as it is and owns its display. A node can be a component that reads grid state, for example the sort direction.
A string header shows the built-in sort arrow on a sorted column, whatever sortable says. sortable: false only stops the header click from sorting. With more than one sort, the arrow also shows the priority number. A node header shows the same arrow. Set sortIndicator: false on the column when the node draws its own arrow.
<DataGridSortIndicator columnId="score" /> is the built-in arrow as a component. It reads the sort of the grid and renders nothing for an unsorted column. Place it inside a node header that sets sortIndicator: false to control where the arrow sits.
| Prop | Type | Default |
|---|---|---|
columnId | string | required |
sortState | readonly SortSpec[] | the sort of the grid |
className | string | none |
headerClickBehavior is a grid prop. A header click selects the column by default. headerClickBehavior="sort" makes the click cycle the sort of the column, and Shift+click adds the column to the sort. This sample builds its own three-state icon:
import type { ReactNode } from "react";
import { Minus, TrendingDown, TrendingUp } from "lucide-react";
import {
DataGrid,
defineColumns,
useDataGridSortState,
} from "@/components/data-grid/data-grid";
type Row = { id: string; name: string; score: number };
function ScoreIcon(): ReactNode {
const sort = useDataGridSortState().find((spec) => spec.columnId === "score");
if (sort?.direction === "asc") return <TrendingUp className="size-3.5" />;
if (sort?.direction === "desc") return <TrendingDown className="size-3.5" />;
return <Minus className="size-3.5 text-muted-foreground" />;
}
const columns = defineColumns<Row>()([
{ id: "name", header: "Name", accessorKey: "name" },
{
id: "score",
header: (
<span className="flex items-center gap-1.5">
Score <ScoreIcon />
</span>
),
accessorKey: "score",
type: "number",
},
]);
export function Scores({ rows }: { rows: Row[] }) {
return (
<DataGrid
className="h-80"
defaultData={rows}
columns={columns}
headerClickBehavior="sort"
/>
);
}If header is a node, the screen reader label, the header menu, the export, and the import matching read its text. In <span><User /> Name</span>, that text is Name. A component inside the node adds no text. Set headerText when the label comes from a component or when it differs from the visible text. A node header with no text and no headerText reads the column id. columnLabelText(column) returns this label.
headerClassName adds classes to the header cell.
Replace the header cell content
ColumnDef.header replaces the label inside the built-in cell. renderHeaderCell on DataGrid replaces everything inside the cell. The grid keeps the cell itself: its place, pin offset, role, aria-colindex, sort and select gestures, and resize handle.
The slot runs once for each visible column. It receives ctx and Default. ctx holds column, index, width, headerClickBehavior, and sortState. Default is the built-in content: the label, the sort arrow, the header filter button, the reorder drag handle on touch screens, and the menu button. A custom node loses all of them. Return Default to keep them:
import { DataGrid } from "@/components/data-grid/data-grid";
// rows and columns as in the first sample
export function CustomHeaderGrid() {
return (
<DataGrid
className="h-80"
defaultData={rows}
columns={columns}
renderHeaderCell={(ctx, Default) =>
ctx.column.id === "name" ? <strong>Name</strong> : Default
}
/>
);
}A press that starts on a button, link, form control, role="button" element, or editable element does not sort, select, or start a reorder. With DataGridRoot children, pass renderHeaderCell to DataGridHeader.
Column groups
columnGroups on DataGrid or DataGridProvider puts a shared header above columns. It names the columns by id, and the columns array stays flat. Groups nest:
import { DataGrid, type ColumnGroupDef } from "@/components/data-grid/data-grid";
const columnGroups: ColumnGroupDef[] = [
{ id: "contact", header: "Contact", children: ["name", "email"] },
{
id: "work",
header: "Work",
children: [
"role",
{ id: "history", header: "History", children: ["joined", "age"] },
],
},
];
// rows and columns hold the name, email, role, joined, and age columns
export function GroupedGrid() {
return (
<DataGrid
defaultData={rows}
columns={columns}
columnGroups={columnGroups}
/>
);
}| Field | Type | Default |
|---|---|---|
id | string | required, unique across groups and columns |
header | string | ReactNode | required |
headerText | string | none |
children | readonly (string | ColumnGroupDef)[] | required |
headerClassName | string | none |
The header has one row for each group level and one row for the column headers. headerHeight sets the height of one row. The header block grows by one row for each level, and the aria-rowindex of data rows grows by the same number. A column outside every group spans all rows. A column in a shallower group spans the rows that remain.
A group keeps its columns together:
- A dragged column moves inside its group, or next to a whole sibling group. A drop that takes it out of its group does nothing.
- A dragged group header moves the group as one block inside its parent. If a member has
reorderable: false, or the members sit in different pin zones, the move does nothing. - A saved or URL
orderthat splits a group gets repaired. All members move to the place of the first member.
Pinning stays per column. A group with columns in two pin zones shows one header cell for each zone. Hiding a column shrinks the group header. Hiding all columns of a group removes it.
Group header behavior:
- In the default
selectmode, a press on a group header selects its visible columns. - Shift extends the selection, and Ctrl or Cmd adds to it.
- Group headers do not sort, resize, or filter.
- The string label of an unpinned group wider than 128 px stays in view while the user scrolls.
- The columns menu of the toolbar lists the members under a heading with the group path, such as
Work / History. - Export and print write the column headers and leave out the group headers.
The grid ignores what it cannot use:
- an id that is not a column
- a column that a second group lists, which stays in the first group
- a group id that repeats or equals a column id
- nesting deeper than 8 levels, and everything after the first 5000 entries
In development, the grid logs each ignored entry once.
The grid keeps the group model when a new columnGroups array has equal content. That includes an inline header node with the same element type, key, and props.