|
| 1 | +--- |
| 2 | +title: Helpers Guide |
| 3 | +--- |
| 4 | + |
| 5 | +## Helpers Guide |
| 6 | + |
| 7 | +TanStack Table exposes a few small helper functions for authoring table configuration with better TypeScript inference. They do not add behavior by themselves. Instead, they help TypeScript preserve the relationship between your feature set, row type, column definitions, table options, and named function registries. |
| 8 | + |
| 9 | +The most common helpers are: |
| 10 | + |
| 11 | +- `tableFeatures` - defines the static feature set and feature-related slots for a table |
| 12 | +- `tableOptions` - preserves inference when composing reusable table options |
| 13 | +- `createColumnHelper` - creates strongly typed column definitions |
| 14 | + |
| 15 | +These helpers are exported from every framework adapter and from `@tanstack/table-core`. |
| 16 | + |
| 17 | +## `tableFeatures` |
| 18 | + |
| 19 | +Use `tableFeatures()` to declare which features a table uses. Features are opt-in in v9, so the object you pass to this helper determines which feature APIs and state slices exist on the table, columns, rows, headers, and cells. |
| 20 | + |
| 21 | +For a basic table that only needs core behavior, pass an empty object: |
| 22 | + |
| 23 | +```ts |
| 24 | +import { tableFeatures } from '@tanstack/react-table' |
| 25 | + |
| 26 | +const features = tableFeatures({}) |
| 27 | +``` |
| 28 | + |
| 29 | +Add feature objects and row model factories when your table needs extra behavior: |
| 30 | + |
| 31 | +```ts |
| 32 | +import { |
| 33 | + columnFilteringFeature, |
| 34 | + createFilteredRowModel, |
| 35 | + createSortedRowModel, |
| 36 | + filterFns, |
| 37 | + rowSortingFeature, |
| 38 | + sortFns, |
| 39 | + tableFeatures, |
| 40 | +} from '@tanstack/react-table' |
| 41 | + |
| 42 | +const features = tableFeatures({ |
| 43 | + columnFilteringFeature, |
| 44 | + rowSortingFeature, |
| 45 | + filteredRowModel: createFilteredRowModel(), |
| 46 | + sortedRowModel: createSortedRowModel(), |
| 47 | + filterFns, |
| 48 | + sortFns, |
| 49 | +}) |
| 50 | +``` |
| 51 | + |
| 52 | +Keep `features` stable. In most apps, define it outside your component or in shared table setup code. Since `typeof features` is used throughout the table's types, stable features also make it easier to reuse column helpers, column definitions, and shared options. |
| 53 | + |
| 54 | +### What goes in `tableFeatures` |
| 55 | + |
| 56 | +`tableFeatures()` is the static configuration point for things that are stitched into a table before it is created: |
| 57 | + |
| 58 | +- Feature objects such as `rowSortingFeature`, `columnFilteringFeature`, or custom features |
| 59 | +- Row model factories such as `createSortedRowModel()` and `createFilteredRowModel()` |
| 60 | +- Function registries such as `filterFns`, `sortFns`, and `aggregationFns` |
| 61 | +- Type-only slots such as `tableMeta` and `columnMeta`, usually declared with `metaHelper` |
| 62 | + |
| 63 | +`metaHelper()` is useful when declaring type-only meta slots in `tableFeatures()`. It is equivalent to writing `{} as MyMeta`, but makes the intent clearer and avoids lint rules accidentally removing the type assertion: |
| 64 | + |
| 65 | +```ts |
| 66 | +import { metaHelper, rowSortingFeature, tableFeatures } from '@tanstack/react-table' |
| 67 | + |
| 68 | +type MyTableMeta = { |
| 69 | + updateData: (rowIndex: number, columnId: string, value: unknown) => void |
| 70 | +} |
| 71 | + |
| 72 | +type MyColumnMeta = { |
| 73 | + align?: 'left' | 'right' |
| 74 | +} |
| 75 | + |
| 76 | +const features = tableFeatures({ |
| 77 | + rowSortingFeature, |
| 78 | + tableMeta: metaHelper<MyTableMeta>(), |
| 79 | + columnMeta: metaHelper<MyColumnMeta>(), |
| 80 | +}) |
| 81 | +``` |
| 82 | + |
| 83 | +For more detail on `tableMeta`, `columnMeta`, and `metaHelper`, see the [Table and Column Meta Guide](./table-and-column-meta). |
| 84 | + |
| 85 | +Function registry keys become valid string references in table and column options: |
| 86 | + |
| 87 | +```ts |
| 88 | +import { |
| 89 | + createColumnHelper, |
| 90 | + createSortedRowModel, |
| 91 | + rowSortingFeature, |
| 92 | + sortFns, |
| 93 | + tableFeatures, |
| 94 | +} from '@tanstack/react-table' |
| 95 | + |
| 96 | +type Person = { |
| 97 | + rank: number |
| 98 | +} |
| 99 | + |
| 100 | +const features = tableFeatures({ |
| 101 | + rowSortingFeature, |
| 102 | + sortedRowModel: createSortedRowModel(), |
| 103 | + sortFns: { |
| 104 | + ...sortFns, |
| 105 | + byRank: (rowA, rowB, columnId) => { |
| 106 | + return rowA.getValue<number>(columnId) - rowB.getValue<number>(columnId) |
| 107 | + }, |
| 108 | + }, |
| 109 | +}) |
| 110 | + |
| 111 | +const columnHelper = createColumnHelper<typeof features, Person>() |
| 112 | + |
| 113 | +const columns = columnHelper.columns([ |
| 114 | + columnHelper.accessor('rank', { |
| 115 | + sortFn: 'byRank', |
| 116 | + }), |
| 117 | +]) |
| 118 | +``` |
| 119 | + |
| 120 | +For more detail on row model slots and function registries, see the [Row Models Guide](./row-models). |
| 121 | + |
| 122 | +## `tableOptions` |
| 123 | + |
| 124 | +Use `tableOptions()` when you want to compose reusable table option objects while keeping TanStack Table's generic inference intact. The helper returns the same object at runtime; its value is in the TypeScript overloads. |
| 125 | + |
| 126 | +This is useful for shared defaults: |
| 127 | + |
| 128 | +```ts |
| 129 | +import { tableFeatures, tableOptions, useTable } from '@tanstack/react-table' |
| 130 | + |
| 131 | +const features = tableFeatures({}) |
| 132 | + |
| 133 | +const sharedOptions = tableOptions({ |
| 134 | + features, |
| 135 | + defaultColumn: { |
| 136 | + minSize: 80, |
| 137 | + maxSize: 400, |
| 138 | + }, |
| 139 | + debugTable: true, |
| 140 | +}) |
| 141 | + |
| 142 | +const table = useTable({ |
| 143 | + ...sharedOptions, |
| 144 | + columns, |
| 145 | + data, |
| 146 | +}) |
| 147 | +``` |
| 148 | + |
| 149 | +It is also useful when a wrapper or table factory supplies required options later. For example, a reusable option fragment can omit `data`, `columns`, or `features` and still keep the remaining table option types connected to the same feature set and row type: |
| 150 | + |
| 151 | +```ts |
| 152 | +import { |
| 153 | + createSortedRowModel, |
| 154 | + rowSortingFeature, |
| 155 | + tableFeatures, |
| 156 | + tableOptions, |
| 157 | + useTable, |
| 158 | +} from '@tanstack/react-table' |
| 159 | + |
| 160 | +type Person = { |
| 161 | + firstName: string |
| 162 | + lastName: string |
| 163 | + age: number |
| 164 | +} |
| 165 | + |
| 166 | +const features = tableFeatures({ |
| 167 | + rowSortingFeature, |
| 168 | + sortedRowModel: createSortedRowModel(), |
| 169 | +}) |
| 170 | + |
| 171 | +const sortableDefaults = tableOptions<typeof features, Person>({ |
| 172 | + initialState: { |
| 173 | + sorting: [{ id: 'lastName', desc: false }], |
| 174 | + }, |
| 175 | +}) |
| 176 | + |
| 177 | +const table = useTable({ |
| 178 | + features, |
| 179 | + columns, |
| 180 | + data, |
| 181 | + ...sortableDefaults, |
| 182 | +}) |
| 183 | +``` |
| 184 | + |
| 185 | +Use `tableOptions()` for reusable configuration. For one-off table setup, passing the object directly to your adapter's table creation function is usually enough. |
| 186 | + |
| 187 | +## `createColumnHelper` |
| 188 | + |
| 189 | +`createColumnHelper()` creates a small set of utilities for authoring column definitions: |
| 190 | + |
| 191 | +- `accessor` creates data columns from an accessor key or accessor function |
| 192 | +- `display` creates display-only columns such as actions or selection controls |
| 193 | +- `group` creates parent columns that contain nested columns |
| 194 | +- `columns` wraps arrays of column definitions to preserve each column's individual value type |
| 195 | + |
| 196 | +The helper is typed by both your feature set and row type: |
| 197 | + |
| 198 | +```ts |
| 199 | +import { createColumnHelper, tableFeatures } from '@tanstack/react-table' |
| 200 | + |
| 201 | +type Person = { |
| 202 | + firstName: string |
| 203 | + lastName: string |
| 204 | + age: number |
| 205 | +} |
| 206 | + |
| 207 | +const features = tableFeatures({}) |
| 208 | +const columnHelper = createColumnHelper<typeof features, Person>() |
| 209 | + |
| 210 | +const columns = columnHelper.columns([ |
| 211 | + columnHelper.accessor('firstName', { |
| 212 | + header: 'First Name', |
| 213 | + }), |
| 214 | + columnHelper.accessor((row) => row.lastName, { |
| 215 | + id: 'lastName', |
| 216 | + header: 'Last Name', |
| 217 | + }), |
| 218 | + columnHelper.display({ |
| 219 | + id: 'actions', |
| 220 | + cell: (info) => `Actions for ${info.row.id}`, |
| 221 | + }), |
| 222 | +]) |
| 223 | +``` |
| 224 | + |
| 225 | +At runtime, the column helper only returns column definition objects. Its main purpose is to infer accessor values, feature-specific column options, and nested column arrays more precisely than plain object literals can in some TypeScript scenarios. |
| 226 | + |
| 227 | +Column definitions have their own guide with the full details on accessor columns, display columns, grouping columns, IDs, and rendering. See the [Column Defs Guide](./column-defs). |
| 228 | + |
| 229 | +## When to Use Each Helper |
| 230 | + |
| 231 | +Use `tableFeatures()` for every v9 table. Even an empty `tableFeatures({})` call clearly declares that the table only uses core features. |
| 232 | + |
| 233 | +Use `tableOptions()` when options are shared, composed, or supplied in multiple steps. Skip it when the options object is only passed directly to `useTable`, `createTable`, `injectTable`, `TableController`, or `constructTable`. |
| 234 | + |
| 235 | +Use `createColumnHelper()` when you want strong column inference, especially for accessor values, custom feature options, and nested column groups. Plain `ColumnDef` objects are still valid when they are easier for your use case. |
0 commit comments