ColumnDef
Look up every field of ColumnDef, the object that defines one column: its value, cell type, size, sort, filter, and look.
A ColumnDef describes one column. It names the column, says how to read and write the value, picks the cell type, and sets size, sort, filter, and look. Pass an array of them to the columns prop.
| Concern | Fields | Section |
|---|---|---|
| Identity and header | id, header, headerText, headerClassName | Fields |
| Value | accessorKey, accessorFn, setValue, readOnly, renderCell, cellClassName | Read and write a value |
| Cell type | type, options | Fields |
| Validation | validate, validationMode | Validation |
| Size | width, minWidth, maxWidth, flex, resizable | Width and flex |
| Sort and filter | sortable, sortCompare, filterable, filter | Sort and filter |
| Layout | pin, pinnable, reorderable, hidden, hideable | Fields |
defineColumns<TData>() returns the column array unchanged. The type key of each column sets its value type and options type. A column without type is a text column. This sample defines three columns:
import { defineColumns } from "@/components/data-grid/data-grid";
type Order = { id: string; symbol: string; qty: number; price: number };
export const columns = defineColumns<Order>()([
{
id: "symbol",
header: "Symbol",
accessorKey: "symbol",
pin: "start",
width: 120,
},
{
id: "qty",
header: "Qty",
accessorKey: "qty",
type: "number",
validate: (value) => (value !== null && value < 0 ? "Use 0 or more" : null),
},
{
id: "total",
header: "Total",
type: "number",
accessorFn: (row) => row.qty * row.price,
flex: 1,
minWidth: 100,
},
]);The symbol column pins to the start side at 120 px. The qty column is a number column that rejects negative values. The total column shows a computed value. It has no setValue, so the grid blocks edits to it. It takes the free width of the grid.
Keep the columns array stable: define it outside the component or memoize it. A new array with the same content on each render triggers a development warning.
Fields
| Field | Type | Default | Description |
|---|---|---|---|
id | string | Required | Stable identity of the column. Duplicate ids trigger a development warning. |
header | string | ReactNode | Required | A string header shows a sort arrow while the column is sorted, also on a sortable: false column. A node renders as given, with no sort arrow. |
headerText | string | text of a node header | Plain-text name for a node header. The screen reader label, the menus, export, import matching, and autosize read it. Without it, they read the text of the elements in the node. When the node has no text, the screen reader label, the menus, export, and import matching read the column id, and autosize measures no header. |
accessorKey | keyof TData (string keys) | none | Row field that holds the value. |
accessorFn | (row) => TValue | none | Computes the value from the row. |
setValue | (row, value) => TData | spread of accessorKey | Returns a new row with the value written. |
type | string | "text" | Key of the cell type. A column without a type renders and edits as text. Its sort ignores case and accents and reads digit runs as numbers. See Sort order. A key that names no registered cell type renders as text and drops edits, pastes, and deletes. A development build warns once. |
options | unknown | none | Settings for the cell type, such as the choices of a select. |
readOnly | boolean | (row) => boolean | none | Blocks edits. The function form decides per row. |
validate | (value, row, ctx) => string | null or a schema | none | Rejects a value. |
validationMode | "block" | "warn" | "block" | What a rejection does to a commit: a single-cell edit, a paste, a fill, updateCells, an import, Delete, and Cut. |
width | number | 150 | Width in px. |
minWidth | number | none | Smallest width in px. |
maxWidth | number | none | Largest width in px. |
flex | number | none | Share of the free width of the grid. |
pin | "start" | "end" | none | Starting pin side, applied when the column id first appears. "start" and "end" follow the inline axis, so both flip in a right-to-left page. |
sortable | boolean | true | false removes the column from header-click sorting, the sort list, and the sort items of the header menu. |
filterable | boolean | true | false removes the column from the filter column picker and the header filter. |
filter | ColumnFilter | from type | Sets the filter capabilities of this column. Each member beats the same member of the cell type. See Sort and filter. |
sortCompare | (a, b) => number | none | Compares two rows for sorting. |
resizable | boolean | true | false removes the resize handle and leaves the column out of autosize. |
reorderable | boolean | true | false stops the drag of this column. setColumnOrder ignores the column. |
pinnable | boolean | true | false turns off pin and unpin. setColumnPin and the pins of a layout leave the column alone. It keeps its pin. |
hideable | boolean | true | false turns off the column row in the columns menu while the column is visible and removes "Hide column" from the header menu. setColumnHidden still hides the column. |
renderCell | (props) => ReactNode | none | Replaces how the cell looks. |
cellClassName | string | (ctx) => string | none | Adds classes to every cell of the column. A text alignment class aligns the cells. See Align a column. |
headerClassName | string | none | Adds classes to the header cell. |
Read and write a value
accessorKey reads a row field and accessorFn computes a value. A column with only accessorFn blocks edits. Add setValue to allow them. Without setValue, a column with accessorKey writes by spreading the row with the new field value. getCellValue(row, column) reads the value of a column from a row the way the grid does. It throws for a column with neither accessorKey nor accessorFn. In a development build, defineColumns warns for a column with neither accessorKey nor accessorFn.
readOnly: true blocks edits. A function receives the row. The grid-wide readOnly prop overrides every column.
renderCell changes the display only. The cell type still handles editing, copy, and sorting. It receives value, row, rowId, columnId, viewRowIndex, column, options, and isActive.
Validation
validate takes a function that returns an error message or null. It also takes any Standard Schema for the value. For a schema, the committed value is the value that the schema returns, so a schema can transform input.
validationMode: "block"refuses the commit. The editor stays open with the message.validationMode: "warn"commits the raw value and flags the cell. The next valid commit of that cell clears the flag. A validator that throws, or a schema promise that rejects, blocks the commit even in a"warn"column.- Paste, fill,
updateCells, and import keep the raw value of a rejected cell in a"warn"column and flag it. In a"block"column they drop the cell. - An async schema works in the editor and in bulk writes. A bulk write runs at most 32 validations at a time.
Width and flex
width starts at 150 px. A resize clamps to maxWidth and to the larger of minWidth and 32 px.
flex shares the free width of the grid among the flex columns, in proportion to their flex values. A column stops at maxWidth, and its unused share goes to the others. A flex column never shrinks below its width. A width override takes the column out of the flex share: a resize, an autosize, setColumnWidth, or a width in the column layout. resetColumnWidth puts it back.
Sort and filter
sortable: falseremoves header-click sorting.setSortsandtoggleSortstill sort the column. URL state drops a sort for asortable: falsecolumn, and a filter for afilterable: falsecolumn.sortComparereceives two whole rows. A result of zero, a non-finite number such asNaN, or a thrown error defers that pair to the default text compare. TheSortSpecdirection still applies, and empty cells still sort last.filterable: falsehides the column from the filter column picker. Filters that already target the column keep applying.filter.matchreceives the raw cell value and the filter. A thrown error fails the row for that filter.filter.operatorswins over thefilter.operatorsof the cell type and the defaults.isAnyOfandisNoneOfuse the built-in set match on the cell text. Yourfilter.matchreceives them only when the samefilterlists them inoperators.filter.matchCase(defaultfalse) makes the built-in text and set operators and the header filter list respect letter case.filter.compareorders cell text against a filter bound forgt,gte,lt,lte, andisBetween. ANaNresult or a throw falls back to the default order. See Filtering.filter.valueInputpicks the value widget of the filter row. It takes a built-in name or a component.- With
sortMode="server", the server orders the rows andsortComparedoes not run. WithfilterMode="server", the server filters andfilter.matchdoes not run.filter.operatorssets the operators of the filter menu in both modes.
Types
ColumnDef<TData, TValue, TValidate> has TValidate set to TValue by default. AnyColumnDef is ColumnDef<unknown, unknown, any>: a column of any row type. useDataGridVisibleColumns() and useDataGridAllColumns() return arrays of it. Pass a row type, such as useDataGridVisibleColumns<Order>(), to get ColumnDefOf<Order> instead. With defineColumns, you never set TValidate yourself.
ColumnDefOf<TData> is ColumnDef<TData, unknown, any>, the column type of the columns prop. Import StandardSchemaV1 from @/components/data-grid/data-grid. StandardSchemaV1.InferInput<S> and StandardSchemaV1.InferOutput<S> give the input and output types of a schema.
TypedColumnDef<TData, K> is the column type for cell type K. AnyTypedColumn<TData> is the union of these types. It is the element type that defineColumns takes. TypedTextColumnDef<TData> is its text branch, where type is optional.
TypeScript generics lists the type arguments of the hooks and the interfaces that you extend.