v9.0.0-beta.10 introduces a breaking change in how row models are defined in order to bring increased type-safety features. Row model factories and function registries now live as slots on the features object instead of a separate rowModels option, and the factories no longer take arguments. If you migrated on an earlier beta, see the Row Model and Function Registry Migration section below for the new shape.
TanStack Table v9 is a major release with explicit feature registration, row model registration, and a new atom-backed state model. The Lit adapter wraps those APIs in a ReactiveController.
The Lit adapter may change during the v9 beta cycle. This guide documents the current local v9 API and avoids speculating about future beta changes.
The main migration is replacing the v8 controller-with-options-thunk with a v9 controller plus .table(options, selector?), then moving feature and row-model setup into the v9 shape.
// v8
private tableController = new TableController(this, () => ({
columns,
data: this.data,
}))
protected render() {
const table = this.tableController.table
return html`...`
}
// v9
private tableController = new TableController<typeof features, Person>(this)
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
})
return html`...`
}// v8
private tableController = new TableController(this, () => ({
columns,
data: this.data,
}))
protected render() {
const table = this.tableController.table
return html`...`
}
// v9
private tableController = new TableController<typeof features, Person>(this)
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
})
return html`...`
}The v9 controller takes the host only. Pass options to .table(...) during render.
// v8
import {
TableController,
getCoreRowModel,
} from '@tanstack/lit-table'
private tableController = new TableController(this, () => ({
columns,
data: this.data,
getCoreRowModel: getCoreRowModel(),
}))
// v9
import {
TableController,
tableFeatures,
} from '@tanstack/lit-table'
const features = tableFeatures({})
private tableController = new TableController<typeof features, Person>(this)
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
})
}// v8
import {
TableController,
getCoreRowModel,
} from '@tanstack/lit-table'
private tableController = new TableController(this, () => ({
columns,
data: this.data,
getCoreRowModel: getCoreRowModel(),
}))
// v9
import {
TableController,
tableFeatures,
} from '@tanstack/lit-table'
const features = tableFeatures({})
private tableController = new TableController<typeof features, Person>(this)
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
})
}Features control which APIs, options, and state slices exist on the table.
import {
columnFilteringFeature,
columnVisibilityFeature,
rowPaginationFeature,
rowSelectionFeature,
rowSortingFeature,
tableFeatures,
} from '@tanstack/lit-table'
const features = tableFeatures({
columnFilteringFeature,
columnVisibilityFeature,
rowPaginationFeature,
rowSelectionFeature,
rowSortingFeature,
})import {
columnFilteringFeature,
columnVisibilityFeature,
rowPaginationFeature,
rowSelectionFeature,
rowSortingFeature,
tableFeatures,
} from '@tanstack/lit-table'
const features = tableFeatures({
columnFilteringFeature,
columnVisibilityFeature,
rowPaginationFeature,
rowSelectionFeature,
rowSortingFeature,
})If a feature is not registered, its APIs and state slice are not available.
stockFeatures is useful for early migration before you audit feature usage.
import { stockFeatures } from '@tanstack/lit-table'
const table = this.tableController.table({
features: stockFeatures,
columns,
data: this.data,
})import { stockFeatures } from '@tanstack/lit-table'
const table = this.tableController.table({
features: stockFeatures,
columns,
data: this.data,
})Use it as a temporary migration shortcut. Explicit feature registration is the production target.
| Feature | Import Name |
|---|---|
| Column Filtering | columnFilteringFeature |
| Global Filtering | globalFilteringFeature |
| Row Sorting | rowSortingFeature |
| Row Pagination | rowPaginationFeature |
| Row Selection | rowSelectionFeature |
| Row Expanding | rowExpandingFeature |
| Row Pinning | rowPinningFeature |
| Column Pinning | columnPinningFeature |
| Column Visibility | columnVisibilityFeature |
| Column Ordering | columnOrderingFeature |
| Column Sizing | columnSizingFeature |
| Column Resizing | columnResizingFeature |
| Column Grouping | columnGroupingFeature |
| Column Faceting | columnFacetingFeature |
Row model factories and function registries are now slots on tableFeatures({...}). The separate rowModels option is removed.
| v8 Option | v9 tableFeatures Slot | v9 Factory / Value |
|---|---|---|
| getCoreRowModel() | (automatic) | Not needed |
| getFilteredRowModel() + filterFns | filteredRowModel + filterFns | createFilteredRowModel() + filterFns |
| getSortedRowModel() + sortingFns | sortedRowModel + sortFns | createSortedRowModel() + sortFns |
| getPaginationRowModel() | paginatedRowModel | createPaginatedRowModel() |
| getExpandedRowModel() | expandedRowModel | createExpandedRowModel() |
| getGroupedRowModel() + aggregationFns | groupedRowModel + aggregationFns | createGroupedRowModel() + aggregationFns |
| getFacetedRowModel() | facetedRowModel | createFacetedRowModel() |
| getFacetedMinMaxValues() | facetedMinMaxValues | createFacetedMinMaxValues() |
| getFacetedUniqueValues() | facetedUniqueValues | createFacetedUniqueValues() |
// v8
import {
TableController,
getCoreRowModel,
getFilteredRowModel,
getPaginationRowModel,
getSortedRowModel,
filterFns,
sortingFns,
} from '@tanstack/lit-table'
private tableController = new TableController(this, () => ({
columns,
data: this.data,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
getPaginationRowModel: getPaginationRowModel(),
filterFns,
sortingFns,
}))// v8
import {
TableController,
getCoreRowModel,
getFilteredRowModel,
getPaginationRowModel,
getSortedRowModel,
filterFns,
sortingFns,
} from '@tanstack/lit-table'
private tableController = new TableController(this, () => ({
columns,
data: this.data,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
getPaginationRowModel: getPaginationRowModel(),
filterFns,
sortingFns,
}))// v9
import {
TableController,
columnFilteringFeature,
createFilteredRowModel,
createPaginatedRowModel,
createSortedRowModel,
filterFns,
rowPaginationFeature,
rowSortingFeature,
sortFns,
tableFeatures,
} from '@tanstack/lit-table'
const features = tableFeatures({
columnFilteringFeature,
rowPaginationFeature,
rowSortingFeature,
filteredRowModel: createFilteredRowModel(),
sortedRowModel: createSortedRowModel(),
paginatedRowModel: createPaginatedRowModel(),
filterFns,
sortFns,
})
private tableController = new TableController<typeof features, Person>(this)
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
})
return html`...`
}// v9
import {
TableController,
columnFilteringFeature,
createFilteredRowModel,
createPaginatedRowModel,
createSortedRowModel,
filterFns,
rowPaginationFeature,
rowSortingFeature,
sortFns,
tableFeatures,
} from '@tanstack/lit-table'
const features = tableFeatures({
columnFilteringFeature,
rowPaginationFeature,
rowSortingFeature,
filteredRowModel: createFilteredRowModel(),
sortedRowModel: createSortedRowModel(),
paginatedRowModel: createPaginatedRowModel(),
filterFns,
sortFns,
})
private tableController = new TableController<typeof features, Person>(this)
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
})
return html`...`
}Lit v9 table state is atom-backed and controller-driven. The controller requests host updates when table store or option store changes.
| Surface | Use |
|---|---|
| table.state | Full registered table state by default, or selected state from the second argument to tableController.table(...). |
| table.store.state | Current full table state snapshot. |
| table.atoms.<slice>.get() | Narrow current-value read for one state slice. |
| table.Subscribe | Template helper for selecting table state while rendering. |
| table.baseAtoms.<slice> | Internal writable atoms. Prefer feature APIs or external atoms. |
// v8
const sorting = table.getState().sorting
// v9: full snapshot
const sorting = table.store.state.sorting
// v9: narrow atom read
const sorting = table.atoms.sorting.get()// v8
const sorting = table.getState().sorting
// v9: full snapshot
const sorting = table.store.state.sorting
// v9: narrow atom read
const sorting = table.atoms.sorting.get()By default, table.state contains the full registered table state.
const table = this.tableController.table({
features,
columns,
data: this.data,
})
const { pagination, sorting } = table.stateconst table = this.tableController.table({
features,
columns,
data: this.data,
})
const { pagination, sorting } = table.statePass a second-argument selector when you want table.state to contain only the values that should be selected for render code.
const table = this.tableController.table(
{
features,
columns,
data: this.data,
},
(state) => ({
pagination: state.pagination,
}),
)
table.state.paginationconst table = this.tableController.table(
{
features,
columns,
data: this.data,
},
(state) => ({
pagination: state.pagination,
}),
)
table.state.paginationPassing (state) => state is equivalent to the default selector and is no longer necessary.
${table.Subscribe({
selector: (state) => ({
pagination: state.pagination,
}),
children: ({ pagination }) => html`
<span>Page ${pagination.pageIndex + 1}</span>
`,
})}${table.Subscribe({
selector: (state) => ({
pagination: state.pagination,
}),
children: ({ pagination }) => html`
<span>Page ${pagination.pageIndex + 1}</span>
`,
})}table.Subscribe can also accept a source, but the current Lit adapter invalidates the host through the table store subscription. Treat source mode as render-time selection convenience.
The preferred v9 pattern for owning state slices is external atoms, described below. The v8-style controlled-state pattern is still supported: use Lit @state() fields with per-slice callbacks.
import { state } from 'lit/decorators.js'
import type { PaginationState, SortingState } from '@tanstack/lit-table'
@state()
private sorting: SortingState = []
@state()
private pagination: PaginationState = {
pageIndex: 0,
pageSize: 10,
}
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
state: {
sorting: this.sorting,
pagination: this.pagination,
},
onSortingChange: (updater) => {
this.sorting =
updater instanceof Function ? updater(this.sorting) : updater
},
onPaginationChange: (updater) => {
this.pagination =
updater instanceof Function ? updater(this.pagination) : updater
},
})
return html`...`
}import { state } from 'lit/decorators.js'
import type { PaginationState, SortingState } from '@tanstack/lit-table'
@state()
private sorting: SortingState = []
@state()
private pagination: PaginationState = {
pageIndex: 0,
pageSize: 10,
}
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
state: {
sorting: this.sorting,
pagination: this.pagination,
},
onSortingChange: (updater) => {
this.sorting =
updater instanceof Function ? updater(this.sorting) : updater
},
onPaginationChange: (updater) => {
this.pagination =
updater instanceof Function ? updater(this.pagination) : updater
},
})
return html`...`
}The v8-style top-level onStateChange callback is gone. Use per-slice callbacks or external atoms.
Use external atoms when the app should own and share state slices outside the table.
import { createAtom } from '@tanstack/store'
import type { PaginationState, SortingState } from '@tanstack/lit-table'
const sortingAtom = createAtom<SortingState>([])
const paginationAtom = createAtom<PaginationState>({
pageIndex: 0,
pageSize: 10,
})
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
atoms: {
sorting: sortingAtom,
pagination: paginationAtom,
},
})
return html`<span>Page ${paginationAtom.get().pageIndex + 1}</span>`
}import { createAtom } from '@tanstack/store'
import type { PaginationState, SortingState } from '@tanstack/lit-table'
const sortingAtom = createAtom<SortingState>([])
const paginationAtom = createAtom<PaginationState>({
pageIndex: 0,
pageSize: 10,
})
protected render() {
const table = this.tableController.table({
features,
columns,
data: this.data,
atoms: {
sorting: sortingAtom,
pagination: paginationAtom,
},
})
return html`<span>Page ${paginationAtom.get().pageIndex + 1}</span>`
}Do not provide both atoms.pagination and state.pagination; the atom owns that slice.
Column helpers and column types now include TFeatures first.
// v8
const columnHelper = createColumnHelper<Person>()
const columns: ColumnDef<Person>[] = [
columnHelper.accessor('age', {
header: 'Age',
sortingFn: 'alphanumeric',
}),
]
// v9
const columnHelper = createColumnHelper<typeof features, Person>()
const columns: Array<ColumnDef<typeof features, Person>> = columnHelper.columns([
columnHelper.accessor('age', {
header: 'Age',
sortFn: 'alphanumeric',
}),
])// v8
const columnHelper = createColumnHelper<Person>()
const columns: ColumnDef<Person>[] = [
columnHelper.accessor('age', {
header: 'Age',
sortingFn: 'alphanumeric',
}),
]
// v9
const columnHelper = createColumnHelper<typeof features, Person>()
const columns: Array<ColumnDef<typeof features, Person>> = columnHelper.columns([
columnHelper.accessor('age', {
header: 'Age',
sortFn: 'alphanumeric',
}),
])Use columnHelper.columns([...]) for better inference across nested columns.
Replace v8 flexRender(def, context) calls with FlexRender({ cell | header | footer }).
// v8
html`<td>${flexRender(cell.column.columnDef.cell, cell.getContext())}</td>`
// v9
html`<td>${FlexRender({ cell })}</td>`
html`<th>${FlexRender({ header })}</th>`
html`<td>${FlexRender({ footer: header })}</td>`// v8
html`<td>${flexRender(cell.column.columnDef.cell, cell.getContext())}</td>`
// v9
html`<td>${FlexRender({ cell })}</td>`
html`<th>${FlexRender({ header })}</th>`
html`<td>${FlexRender({ footer: header })}</td>`The table instance also exposes table.FlexRender:
html`<td>${table.FlexRender({ cell })}</td>`html`<td>${table.FlexRender({ cell })}</td>`tableOptions() helps compose shared table option fragments.
import { tableOptions } from '@tanstack/lit-table'
const baseOptions = tableOptions({
features,
defaultColumn: {
minSize: 40,
},
})
const table = this.tableController.table({
...baseOptions,
columns,
data: this.data,
})import { tableOptions } from '@tanstack/lit-table'
const baseOptions = tableOptions({
features,
defaultColumn: {
minSize: 40,
},
})
const table = this.tableController.table({
...baseOptions,
columns,
data: this.data,
})createTableHook creates shared Lit table helpers with features (including row model slots) and render helpers already bound.
import { createTableHook } from '@tanstack/lit-table'
export const { useAppTable, createAppColumnHelper } = createTableHook({ features })
const columnHelper = createAppColumnHelper<Person>()
@customElement('people-table')
class PeopleTable extends LitElement {
private appTable = useAppTable(this, {
columns,
data: this.data,
})
protected render() {
const table = this.appTable.table()
return html`...`
}
}import { createTableHook } from '@tanstack/lit-table'
export const { useAppTable, createAppColumnHelper } = createTableHook({ features })
const columnHelper = createAppColumnHelper<Person>()
@customElement('people-table')
class PeopleTable extends LitElement {
private appTable = useAppTable(this, {
columns,
data: this.data,
})
protected render() {
const table = this.appTable.table()
return html`...`
}
}See the Composable Tables Guide for full patterns.
Table-level enablePinning split into:
enableColumnPinning: true
enableRowPinning: trueenableColumnPinning: true
enableRowPinning: trueColumn resizing now has its own feature and state slice.
const features = tableFeatures({
columnSizingFeature,
columnResizingFeature,
})const features = tableFeatures({
columnSizingFeature,
columnResizingFeature,
})columnSizingInfo became columnResizing, and onColumnSizingInfoChange became onColumnResizingChange.
| v8 | v9 |
|---|---|
| sortingFn | sortFn |
| sortingFns | sortFns |
| getSortingFn() | getSortFn() |
| getAutoSortingFn() | getAutoSortFn() |
| SortingFn | SortFn |
Underscore-prefixed APIs that are now public should be called without _, such as row.getAllCellsByColumnId().
Use TFeatures as the first generic:
ColumnDef<typeof features, Person>
Column<typeof features, Person>
Row<typeof features, Person>
Table<typeof features, Person>ColumnDef<typeof features, Person>
Column<typeof features, Person>
Row<typeof features, Person>
Table<typeof features, Person>const features = tableFeatures({
rowSortingFeature,
rowPaginationFeature,
})
const columnHelper = createColumnHelper<typeof features, Person>()const features = tableFeatures({
rowSortingFeature,
rowPaginationFeature,
})
const columnHelper = createColumnHelper<typeof features, Person>()import type { StockFeatures } from '@tanstack/lit-table'
type PersonColumn = ColumnDef<StockFeatures, Person>import type { StockFeatures } from '@tanstack/lit-table'
type PersonColumn = ColumnDef<StockFeatures, Person>No more declaration merging required! (Although it still works if you want to keep using it)
Global declaration merging works exactly like it did in v8. The only change you need to make is updating the generics shape: both interfaces now take TFeatures as the first type parameter.
declare module '@tanstack/lit-table' {
interface ColumnMeta<TFeatures, TData, TValue> {
align?: 'left' | 'right'
}
}declare module '@tanstack/lit-table' {
interface ColumnMeta<TFeatures, TData, TValue> {
align?: 'left' | 'right'
}
}That's all that's required if you want to keep declaring meta types globally.
Optionally, v9 also adds a new way to declare meta types per-table without declaration merging. You can use type-only tableMeta/columnMeta slots on the features option, which only affect tables created with that features object:
const features = tableFeatures({
rowSortingFeature,
columnMeta: metaHelper<{ align?: 'left' | 'right' }>(),
})const features = tableFeatures({
rowSortingFeature,
columnMeta: metaHelper<{ align?: 'left' | 'right' }>(),
})See the new Table and Column Meta Guide for full details on both approaches.
In v8, making a custom function usable as a string reference (like filterFn: 'fuzzy') required declare module augmentation of the FilterFns interface, and typing filter meta required augmenting FilterMeta. In v9, registering the function in the matching registry slot does both jobs with no global augmentation:
// v8
declare module '@tanstack/lit-table' {
interface FilterFns {
fuzzy: FilterFn<unknown>
}
interface FilterMeta {
itemRank: RankingInfo
}
}
// v9 - register in the slot; the key becomes a valid string value
interface FuzzyFilterMeta {
itemRank?: RankingInfo
}
const features = tableFeatures({
columnFilteringFeature,
filteredRowModel: createFilteredRowModel(),
filterFns: { ...filterFns, fuzzy: fuzzyFilter },
filterMeta: metaHelper<FuzzyFilterMeta>(),
})
// 'fuzzy' now typechecks in column defs for tables using these features
columnHelper.accessor('name', { filterFn: 'fuzzy' })// v8
declare module '@tanstack/lit-table' {
interface FilterFns {
fuzzy: FilterFn<unknown>
}
interface FilterMeta {
itemRank: RankingInfo
}
}
// v9 - register in the slot; the key becomes a valid string value
interface FuzzyFilterMeta {
itemRank?: RankingInfo
}
const features = tableFeatures({
columnFilteringFeature,
filteredRowModel: createFilteredRowModel(),
filterFns: { ...filterFns, fuzzy: fuzzyFilter },
filterMeta: metaHelper<FuzzyFilterMeta>(),
})
// 'fuzzy' now typechecks in column defs for tables using these features
columnHelper.accessor('name', { filterFn: 'fuzzy' })The same pattern applies to sortFns (for sortFn string values) and aggregationFns (for aggregationFn string values). See the Fuzzy Filtering Guide for a complete example.
Prefer explicit object row types:
type Person = {
firstName: string
lastName: string
age: number
}type Person = {
firstName: string
lastName: string
age: number
}