migrate-v8-to-v9

name	migrate-v8-to-v9
description	Complete Lit v8-to-v9 migration reference: TableController construction, explicit features and row-model slots, selected/atom state, FlexRender, createTableHook, type generics, prototype methods, sorting, sizing, selection, and logical pinning.
metadata	{"type":"lifecycle","library":"@tanstack/lit-table","framework":"lit","library_version":"9.2.4"}
requires	["@tanstack/table-core#migrate-v8-to-v9","getting-started","table-state"]
sources	["TanStack/table:docs/framework/lit/guide/migrating.md","TanStack/table:packages/lit-table/src/index.ts","TanStack/table:examples/lit/basic-table-controller"]

Use this as the complete breaking-change checklist. V9 is the current API. The central Lit change is a stable controller constructed with the host, while current options are passed to .table(...) during render.

Framework prerequisites: Lit 3.1.3 or newer within v3 (lit ^3.1.3) and @lit/context ^1.1.0.

Recommended Migration Order

1. Replace the v8 controller options thunk with a host-only typed TableController.
2. Pass current options to controller.table(options, selector?) in render.
3. Move features, row models, and registries into tableFeatures.
4. Update selected state, controlled ownership, and rendering.
5. Apply every shared API and type rename below.
6. Treat stockFeatures as a temporary audit bridge; explicit features are the production target.

const features = tableFeatures({
  rowSortingFeature,
  sortedRowModel: createSortedRowModel(),
  sortFns: { alphanumeric: sortFn_alphanumeric },
})

class PeopleTable extends LitElement {
  private controller = new TableController<typeof features, Person>(this)

  protected render() {
    const table = this.controller.table({ features, columns, data: this.data })
    return html`<span>${table.getRowModel().rows.length} rows</span>`
  }
}

Construction and Feature Registration

v8	v9
new TableController(this, () => options)	new TableController<typeof features, TData>(this)
controller.table property	controller.table(options, selector?) call in render
All features bundled	Required features: tableFeatures({...})
getCoreRowModel() option	Remove; core row model is automatic
get*RowModel() table options	create*RowModel() slots in tableFeatures
sortingFns table option	sortFns feature slot
Top-level onStateChange	Per-slice callbacks, external atoms, or store subscription

Feature imports are cellSelectionFeature, columnFilteringFeature, globalFilteringFeature, rowSortingFeature, rowPaginationFeature, rowSelectionFeature, rowExpandingFeature, rowPinningFeature, columnPinningFeature, columnVisibilityFeature, columnOrderingFeature, columnSizingFeature, columnResizingFeature, rowAggregationFeature, columnGroupingFeature, and columnFacetingFeature. APIs are feature-gated. Put a feature before its dependent slot in one tableFeatures call. Aggregation is independent from grouping: register rowAggregationFeature for aggregation APIs and add columnGroupingFeature only for grouped rows.

Row-model mapping

v8 option	v9 slot and factory
getFilteredRowModel()	filteredRowModel: createFilteredRowModel() after column filtering
getSortedRowModel()	sortedRowModel: createSortedRowModel() after row sorting
getPaginationRowModel()	paginatedRowModel: createPaginatedRowModel() after pagination
getExpandedRowModel()	expandedRowModel: createExpandedRowModel() after expanding
getGroupedRowModel()	groupedRowModel: createGroupedRowModel() after grouping
getFacetedRowModel()	facetedRowModel: createFacetedRowModel() after faceting
getFacetedMinMaxValues()	facetedMinMaxValues: createFacetedMinMaxValues()
getFacetedUniqueValues()	facetedUniqueValues: createFacetedUniqueValues()

Factories take no arguments. Register filterFns, sortFns, and aggregationFns as sibling feature slots holding individually imported built-ins (filterFn_includesString, sortFn_alphanumeric, aggregationFn_sum) under their conventional keys. The full registry objects still work but bundle every built-in.

Lit State Migration

• table.getState().sorting becomes table.state.sorting, table.store.state.sorting, or narrow table.atoms.sorting.get().
• table.state contains all registered slices by default. Pass a second-argument selector to controller.table(...) only to narrow the render-selected surface.
• Use table.subscribe(table.store, stableSelector, renderCallback) for selected template state. Keep the selector reference stable outside render.
• Controlled state uses Lit @state() fields and matching on[State]Change callbacks that resolve value-or-function updaters.
• Top-level onStateChange is removed. Use per-slice callbacks, external atoms, or table.store.subscribe for all changes.
• External atoms come from @tanstack/store and are provided through atoms. Never provide both atoms.pagination and state.pagination.
• The controller requests host updates for table and option-store changes; do not create a new controller in render.
• Treat table.baseAtoms as internal writable state; prefer feature APIs or external atoms.

Rendering and Composition

v8	v9
flexRender(def, context)	FlexRender({ cell }), FlexRender({ header }), or FlexRender({ footer })
Standalone helper only	table.FlexRender({ cell }) is also available
Repeated raw options	tableOptions(...) composition
Repeated conventions	createTableHook({ features, ... })

createTableHook returns a host-bound app table helper and pre-bound column helper. Construct the app helper with the Lit host, then call its .table() during render. It is optional and intended for recurring application conventions.

Complete Shared Breaking-Change Map

Instance methods

Row, cell, column, header, and related methods now live on shared prototypes and use this. Call them on their instances. Do not destructure/pass them bare or expect them in object spread, Object.keys, or JSON. Table methods are not affected.

Logical column pinning

V9 has no left/right aliases.

old	new
columnPinning.left / .right	.start / .end
column.pin('left' | 'right')	column.pin('start' | 'end')
getIsPinned() === 'left' | 'right'	'start' | 'end'
row.getLeftVisibleCells() / getRightVisibleCells()	getStartVisibleCells() / getEndVisibleCells()
getLeftHeaderGroups() / getRightHeaderGroups()	getStartHeaderGroups() / getEndHeaderGroups()
getLeftFooterGroups() / getRightFooterGroups()	getStartFooterGroups() / getEndFooterGroups()
getLeftFlatHeaders() / getRightFlatHeaders()	getStartFlatHeaders() / getEndFlatHeaders()
getLeftLeafHeaders() / getRightLeafHeaders()	getStartLeafHeaders() / getEndLeafHeaders()
getLeftLeafColumns() / getRightLeafColumns()	getStartLeafColumns() / getEndLeafColumns()
getLeftVisibleLeafColumns() / getRightVisibleLeafColumns()	getStartVisibleLeafColumns() / getEndVisibleLeafColumns()
getLeftTotalSize() / getRightTotalSize()	getStartTotalSize() / getEndTotalSize()
column.getStart('left')	column.getStart('start')
column.getAfter('right')

Prefer CSS logical inset properties; logical names do not set DOM direction. columnResizeDirection is unchanged.

Pinning, sizing, and resizing

• enablePinning splits into enableColumnPinning and enableRowPinning.
• Interactive resizing requires columnSizingFeature and columnResizingFeature; fixed sizing needs only sizing.
• columnSizingInfo becomes columnResizing.
• setColumnSizingInfo() becomes setColumnResizing().
• onColumnSizingInfoChange becomes onColumnResizingChange.

Sorting, rows, and selection

v8	v9
sortingFn	sortFn
sortingFns	sortFns
getSortingFn()	getSortFn()
getAutoSortingFn()	getAutoSortFn()
SortingFn / SortingFns	SortFn / SortFns
row._getAllCellsByColumnId()	row.getAllCellsByColumnId()

Other _-prefixed internals are removed, including _getPinnedRows, _getFacetedRowModel, _getFacetedMinMaxValues, and _getFacetedUniqueValues.

getIsSomeRowsSelected() and getIsSomePageRowsSelected() mean at least one, including all. Use getIsSomeRowsSelected() && !getIsAllRowsSelected() or getIsSomePageRowsSelected() && !getIsAllPageRowsSelected() for indeterminate UI.

TypeScript Migration

• Add TFeatures first: ColumnDef<typeof features, Person>, Column<typeof features, Person>, Row<typeof features, Person>, Table<typeof features, Person>.
• Replace createColumnHelper<Person>() with createColumnHelper<typeof features, Person>(); use columnHelper.columns([...]) for inference.
• Use StockFeatures when using stockFeatures.
• Existing TableMeta/ColumnMeta declaration merging must add TFeatures first. Prefer per-table tableMeta/columnMeta: metaHelper<...>() slots.
• Replace global FilterFns, SortFns, AggregationFns, and FilterMeta augmentation with registry slots and filterMeta: metaHelper<...>(); registered keys become valid strings.
• RowData is restricted to records or arrays; prefer explicit object row types.

Common Migration Failures

CRITICAL: Keeping the v8 controller shape

The controller constructor takes only the host in v9. Pass options to .table(...) while rendering.

HIGH: Recreating the controller in render

Keep one stable controller field so subscriptions and host lifecycle remain attached.

HIGH: Leaving row models on table options

Move each row model beside its prerequisite feature in tableFeatures.

HIGH: Unstable table.subscribe selector

Define the selector as a class field or outside render to prevent avoidable update churn.

HIGH: Destructuring instance methods

Use row.getValue('name'); prototype methods require the original instance and are absent from shallow clones.

Final Checklist

• TableController is host-only, stable, typed with features/data, and options move to .table(...).
• Features, row models, and registries are in tableFeatures; core row model is removed.
• State reads use selected state, atoms, or store intentionally; selectors are stable.
• onStateChange is replaced; controlled and external-atom ownership do not overlap.
• Rendering uses the v9 FlexRender object helpers.
• Prototype methods, pinning, sizing/resizing, sorting, row, and selection changes are audited.
• Helpers, types, meta, registries, and RowData use v9 shapes.
• Temporary stockFeatures usage has an explicit removal plan.

API Discovery

Inspect node_modules/@tanstack/lit-table/dist/index.d.ts and TableController.d.ts. Verify feature slots and the exact installed v9 APIs in node_modules/@tanstack/table-core/dist/; do not reconstruct v9 from v8 memory.