gridcn2.0.0
Components and props

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.

ConcernFieldsSection
Identity and headerid, header, headerText, headerClassNameFields
ValueaccessorKey, accessorFn, setValue, readOnly, renderCell, cellClassNameRead and write a value
Cell typetype, optionsFields
Validationvalidate, validationModeValidation
Sizewidth, minWidth, maxWidth, flex, resizableWidth and flex
Sort and filtersortable, sortCompare, filterable, filterSort and filter
Layoutpin, pinnable, reorderable, hidden, hideableFields

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

FieldTypeDefaultDescription
idstringRequiredStable identity of the column. Duplicate ids trigger a development warning.
headerstring | ReactNodeRequiredA 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.
headerTextstringtext of a node headerPlain-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.
accessorKeykeyof TData (string keys)noneRow field that holds the value.
accessorFn(row) => TValuenoneComputes the value from the row.
setValue(row, value) => TDataspread of accessorKeyReturns a new row with the value written.
typestring"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.
optionsunknownnoneSettings for the cell type, such as the choices of a select.
readOnlyboolean | (row) => booleannoneBlocks edits. The function form decides per row.
validate(value, row, ctx) => string | null or a schemanoneRejects 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.
widthnumber150Width in px.
minWidthnumbernoneSmallest width in px.
maxWidthnumbernoneLargest width in px.
flexnumbernoneShare of the free width of the grid.
pin"start" | "end"noneStarting 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.
sortablebooleantruefalse removes the column from header-click sorting, the sort list, and the sort items of the header menu.
filterablebooleantruefalse removes the column from the filter column picker and the header filter.
filterColumnFilterfrom typeSets the filter capabilities of this column. Each member beats the same member of the cell type. See Sort and filter.
sortCompare(a, b) => numbernoneCompares two rows for sorting.
hiddenbooleannonetrue hides the column when its id first appears. setColumnHidden and the columns menu change it later.
resizablebooleantruefalse removes the resize handle and leaves the column out of autosize.
reorderablebooleantruefalse stops the drag of this column. setColumnOrder ignores the column.
pinnablebooleantruefalse turns off pin and unpin. setColumnPin and the pins of a layout leave the column alone. It keeps its pin.
hideablebooleantruefalse 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) => ReactNodenoneReplaces how the cell looks.
cellClassNamestring | (ctx) => stringnoneAdds classes to every cell of the column. A text alignment class aligns the cells. See Align a column.
headerClassNamestringnoneAdds 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: false removes header-click sorting. setSorts and toggleSort still sort the column. URL state drops a sort for a sortable: false column, and a filter for a filterable: false column.
  • sortCompare receives two whole rows. A result of zero, a non-finite number such as NaN, or a thrown error defers that pair to the default text compare. The SortSpec direction still applies, and empty cells still sort last.
  • filterable: false hides the column from the filter column picker. Filters that already target the column keep applying.
  • filter.match receives the raw cell value and the filter. A thrown error fails the row for that filter.
  • filter.operators wins over the filter.operators of the cell type and the defaults.
  • isAnyOf and isNoneOf use the built-in set match on the cell text. Your filter.match receives them only when the same filter lists them in operators.
  • filter.matchCase (default false) makes the built-in text and set operators and the header filter list respect letter case.
  • filter.compare orders cell text against a filter bound for gt, gte, lt, lte, and isBetween. A NaN result or a throw falls back to the default order. See Filtering.
  • filter.valueInput picks the value widget of the filter row. It takes a built-in name or a component.
  • With sortMode="server", the server orders the rows and sortCompare does not run. With filterMode="server", the server filters and filter.match does not run. filter.operators sets 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.

On this page