lit-migrate-v8-to-v9

name: lit/migrate-v8-to-v9 description: > Mechanical breaking-change migration from TanStack Table v8 to v9 for @tanstack/lit-table. v8's TableController(host, () => options) shape collapses to v9's new TableController(host) + .table(options, selector?); per-row-model get*RowModel options become tableFeatures({...}) slots (row model factories live on the features object, not a separate rowModels map); flexRender(def, ctx) becomes FlexRender({ cell|header|footer }); core types gain a TFeatures first generic. Routing keywords: lit v8 to v9, migration, TableController v8, get*RowModel, features lit. type: lifecycle library: tanstack-table framework: lit library_version: '9.0.0-alpha.48' requires: - setup - state-management - column-definitions sources: - TanStack/table:docs/framework/lit/lit-table.md - TanStack/table:docs/framework/lit/guide/table-state.md - TanStack/table:docs/framework/react/guide/use-legacy-table.md - TanStack/table:packages/lit-table/src/TableController.ts

Maintainer note: the Lit adapter is scheduled for a rewrite alongside TanStack Lit Store during the v9 beta cycle. APIs in this skill may change in a future beta. The patterns below match 9.0.0-alpha.48.

The Lit v9 adapter mirrors v9's React surface (atoms, features with row model factory slots, FlexRender) wrapped in a ReactiveController. There is no useLegacyTable shim; migrate directly.

The Core Mapping

Source: docs/framework/lit/lit-table.md; packages/lit-table/src/TableController.ts.

Migration Steps

1. Update the controller construction

// v8 — controller takes a thunk that returns options.
private tableController = new TableController(this, () => ({
  columns,
  data: this.data,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
}))

protected render() {
  const table = this.tableController.table // property
  return html`...`
}

// v9 — controller takes only the host. Options pass to .table(...) inside render.
private tableController = new TableController<typeof features, Person>(this)

protected render() {
  const table = this.tableController.table(
    {
      features,
      columns,
      data: this.data,
    },
    () => ({}), // optional selector
  )

  return html`...`
}

2. Replace get*RowModel options with tableFeatures({...}) slots

// v8
{
  columns, data,
  getCoreRowModel:       getCoreRowModel(),
  getSortedRowModel:     getSortedRowModel(),
  getFilteredRowModel:   getFilteredRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
}

// v9 — row model factories and fn maps live on the features object
const features = tableFeatures({
  rowSortingFeature,
  columnFilteringFeature,
  rowPaginationFeature,
  sortedRowModel:    createSortedRowModel(),
  filteredRowModel:  createFilteredRowModel(),
  paginatedRowModel: createPaginatedRowModel(),
  sortFns,
  filterFns,
})

{
  features,
  columns, data,
}

Move features to module scope. Reference identity matters. Source: docs/framework/lit/lit-table.md.

3. Update column types and helpers

// v8
const columnHelper = createColumnHelper<Person>()
const columns: ColumnDef<Person>[] = columnHelper.columns([
  /* … */
])

// v9
const columnHelper = createColumnHelper<typeof features, Person>()
const columns: Array<ColumnDef<typeof features, Person>> = columnHelper.columns(
  [
    /* … */
  ],
)

TFeatures is now the first generic on ColumnDef, Table, and createColumnHelper.

4. Replace flexRender calls

// v8
<td>${flexRender(cell.column.columnDef.cell, cell.getContext())}</td>

// v9 — uses the FlexRender component
<td>${FlexRender({ cell })}</td>
<th>${FlexRender({ header })}</th>
<th>${FlexRender({ footer: header })}</th>

FlexRender handles grouping placeholder / aggregated branches when columnGroupingFeature is registered.

Source: packages/lit-table/src/flexRender.ts.

5. Move to slice atoms (optional but preferred)

// v8 / v9 fallback — @state() field + onStateChange
@state() private _sorting: SortingState = []

protected render() {
  const table = this.tableController.table({
    /* … */,
    state: { sorting: this._sorting },
    onSortingChange: (u) => {
      this._sorting = u instanceof Function ? u(this._sorting) : u
    },
  })
}

// v9 preferred — external atom (per-slice ownership, no on*Change needed)
import { createAtom } from '@tanstack/store'

const sortingAtom = createAtom<SortingState>([])

protected render() {
  const table = this.tableController.table({
    /* … */,
    atoms: { sorting: sortingAtom },
  })
}

Source: examples/lit/basic-external-atoms/src/main.ts.

6. Drop onStateChange

The v8-style global onStateChange is gone. Subscribe per-slice with on*Change, an external atom, or table.store.subscribe(...) if you really need every change.

Common Mistakes

CRITICAL Keeping the v8 controller-with-thunk shape

Wrong:

// v8 shape — `controller.table` was a property
private tableController = new TableController(this, () => ({ columns, data: this.data }))

protected render() {
  const table = this.tableController.table // no longer a property in v9
}

Correct: drop the thunk; call .table(options, selector?) each render. Source: packages/lit-table/src/TableController.ts.

CRITICAL Keeping get*RowModel options after upgrading

Wrong:

this.tableController.table({
  features,
  columns,
  data,
  getSortedRowModel: getSortedRowModel(), // ignored
})

Correct:

const features = tableFeatures({
  rowSortingFeature,
  sortedRowModel: createSortedRowModel(),
  sortFns,
})
this.tableController.table({
  features,
  columns,
  data,
})

v9 doesn't read get*RowModel options. Features and their row model factories are registered together in tableFeatures({...}).

CRITICAL Calling a feature API without registering the feature

Wrong:

const features = tableFeatures({}) // no rowSelectionFeature
const table = this.tableController.table({
  features,
  columns,
  data,
})
table.getIsAllRowsSelected() // type error / runtime no-op

Correct:

const features = tableFeatures({ rowSelectionFeature })
const table = this.tableController.table({
  features,
  columns,
  data,
  enableRowSelection: true,
})

This is the #1 v9 trap. Source: docs/guide/features.md.

HIGH Re-using getCoreRowModel: getCoreRowModel()

Wrong: still passing getCoreRowModel — v9 includes the core row model automatically.

Correct: drop it. The core row model is always included automatically.

HIGH Single-generic column helper / ColumnDef

Wrong:

const columnHelper = createColumnHelper<Person>()
const columns: ColumnDef<Person>[] = [
  /* … */
]

Correct:

const columnHelper = createColumnHelper<typeof features, Person>()
const columns: Array<ColumnDef<typeof features, Person>> = [
  /* … */
]

HIGH Reimplementing built-ins

Wrong: hand-rolled sort/filter/pagination outside the table — #1 AI tell.

Correct: register the matching feature + factory and use the feature APIs. Source: docs/guide/features.md.

MEDIUM Calling flexRender directly when grouping is registered

Wrong: flexRender(cell.column.columnDef.cell, cell.getContext()) for an aggregated/placeholder cell.

Correct: use FlexRender({ cell }) — it handles the aggregated/placeholder branches when columnGroupingFeature is registered.

See Also

• tanstack-table/lit/getting-started — green-field v9 setup.
• tanstack-table/lit/lit-table-controller — controller lifecycle in depth.
• tanstack-table/lit/table-state — atoms, Subscribe, createTableHook.