Column visibility
Hide and show columns from code, a menu, or a column definition, and read column state in your own UI.
Users hide the columns they do not need. hidden: true starts a column hidden. setColumnHidden toggles a column from code. DataGridColumnsMenu gives users a checkbox for each column.
Resize a header edge, drag a header, or pin/hide a column (header menu / columns menu) — every change persists and is restored on the next reload. Current order: (defaults or saved)
Hide and show columns
hidden: true in a ColumnDef sets the first state. setColumnHidden(id, hidden) and the columns menu override it. The flag applies once for each column id, when the id first appears. A new columns array keeps the visibility of the columns it already has and seeds only new ids.
A hidden column is left out of the export and of quick search matches. A filter or sort on it stays active, and the columns menu marks its row. Clear it in the filter menu or with setFilterState.
DataGridColumnsMenu ships with the toolbar add-on. It is a dropdown with a checked row for each column. The header menu of the context menu add-on has a "Hide column" item.
hideable: false protects a key column. The columns menu shows its row checked and turned off while the column is visible. If code hid the column, the row is unchecked and a click shows the column again. The header menu has no "Hide column" item. setColumnHidden, URL state, saved views, and hidden still apply to the column.
This sample sets hideable: false on the name column:
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
defineColumns,
} from "@/components/data-grid/data-grid";
import {
DataGridColumnsMenu,
DataGridToolbar,
} from "@/components/data-grid-toolbar/data-grid-toolbar";
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", hideable: false },
{ id: "email", header: "Email", accessorKey: "email", hidden: true },
]);
export function ColumnsGrid() {
return (
<DataGridProvider defaultData={rows} columns={columns}>
<DataGridToolbar>
<DataGridColumnsMenu />
</DataGridToolbar>
<DataGridRoot className="h-80">
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
);
}Result: the grid starts with the Name column. The menu shows Name checked and turned off, and Email unchecked.
Read column state
These hooks read column state for your own UI. Call them under DataGridProvider.
| Hook | Returns |
|---|---|
useDataGridVisibleColumns() | the columns that are not hidden, in display order |
useDataGridAllColumns() | every column, hidden ones included, in column order |
useDataGridIsColumnHidden(id) | true while the column is hidden |
useDataGridColumnWidth(id) | the stored width in px, or undefined while the column has none |
useDataGridColumnWidths(ids) | the stored widths of a list of columns |
The visible and all-columns hooks return the full ColumnDef of each column. Pass your row type, for example useDataGridVisibleColumns<Row>(), to type accessorFn and setValue. The actions of useDataGridActions() write the state: setColumnWidth, previewColumnWidth, resetColumnWidth, setColumnOrder, setColumnPin, setColumnHidden, setColumnLayout, and autosizeColumns. This sample shows a button for each hidden column:
import {
columnLabelText,
useDataGridActions,
useDataGridAllColumns,
useDataGridIsColumnHidden,
} from "@/components/data-grid/data-grid";
function ShowButton({ id, label }: { id: string; label: string }) {
const actions = useDataGridActions();
const hidden = useDataGridIsColumnHidden(id);
if (!hidden) return null;
return (
<button onClick={() => actions.setColumnHidden(id, false)}>
Show {label}
</button>
);
}
function RestoreBar() {
return useDataGridAllColumns().map((column) => (
<ShowButton
key={column.id}
id={column.id}
label={columnLabelText(column)}
/>
));
}columnLabelText(column) returns the label the grid shows: headerText, the text of a node header, or the column id.
Save the layout
Save a column layout stores hidden columns with widths, order, and pins.
Server mode
The layout is browser state in every data mode. fetchRows gets no list of hidden columns. A hidden column still loads its data. To keep a field from the browser, leave it out of the server answer: see Lock cells by role.
Related
- Column order and pinning
- Save a column layout
- Remember filters and layout: keep hidden columns across visits
- Lock cells by role: remove columns that a role must not see
- ColumnDef reference