Property-backed columns
Define fields read directly from typed row objects.
TanStack · Type Alias
ColumnDef
ColumnDef is TanStack Table's union type for describing display, group, and accessor columns. Its generics type the feature set, row data, and cell values.
How it works
ColumnDef is a union describing a table column: a display column, a group column containing child definitions, or an accessor column that extracts row data. Its generics specify the table features, row type, and cell-value type.
Syntax
type ColumnDef<TFeatures, TData, TValue> = DisplayColumnDef<TFeatures, TData, TValue> | GroupColumnDef<TFeatures, TData, TValue> | AccessorColumnDef<TFeatures, TData, TValue>;Parameters
| Name | Type | Description |
|---|---|---|
TFeatures | extends TableFeatures | The enabled table feature set used by the definition types. |
TData | extends RowData | The row-data type used by the table. |
TValue | extends CellData = CellData | The cell-value type; defaults to CellData. |
Returns
A union type for display, group, and accessor column definitions; it does not define a runtime return value.
Key points
- ColumnDef is a type union rather than one single column shape.
- Display columns are one of the three principal ColumnDef variants.
- Group columns provide a way to include child column definitions.
- Accessor columns describe definitions that obtain values from each row.
- An accessor function receives the original typed row and its index.
- Nested child definitions are represented by an array of ColumnDef values.
- Custom metadata is available through the normalized column's columnDef.meta property.
Common mistakes
- A header string can supply a default column ID, but relying on it is less explicit than setting id yourself when needed.
- Group columns organize child definitions and do not themselves represent a directly accessed row value.
- accessorKey must identify a property on each row that supplies the column value.
Example: Basic typed column definitions
import type { ColumnDef } from '@tanstack/react-table'
type Person = { firstName: string; age: number }
const columns: ColumnDef<Person>[] = [
{ accessorKey: 'firstName', header: 'First name' },
{ accessorKey: 'age', header: 'Age' },
]Defines typed table columns by mapping row-object keys to displayed headers.
When to use it
Computed columns
Build values derived from multiple row fields.
Grouped columns
Arrange related columns under a shared heading.
Column metadata
Attach application-specific configuration to columns.
Interview questions
QWhat is ColumnDef and what are its generic parameters?
ColumnDef<TFeatures, TData, TValue> is a union of display, group, and accessor column definitions. TFeatures describes enabled table features, TData is the row type, and TValue defaults to CellData.
Follow-up: How would you model a computed column? Use an accessor column with accessorFn, whose function receives the original row and index and returns the value.
QWhen should accessorKey and accessorFn be used?
Use accessorKey when the value comes directly from a row property. Use accessorFn when the value must be computed from the original row.
Follow-up: What information does an accessorFn receive? It receives originalRow: TData and index: number, and returns any.
QHow are column content and metadata configured?
A column definition can include header, footer, and cell render templates. A template may be a string or a function receiving the relevant context, with the exact rendered result depending on the adapter.
Follow-up: Where can column metadata be read? Through column.columnDef.meta whenever the column is available.
Related
ColumnDefTemplateColumn APIsTable APIsAccessorColumnDefDisplayColumnDefGroupColumnDef