lit-compose-with-tanstack-virtual

name	lit/compose-with-tanstack-virtual
description	TanStack Table does NOT include virtualization — pair with `@tanstack/lit-virtual`. The standard pattern: get the row array from `table.getRowModel().rows`, construct a `VirtualizerController(host, opts)` alongside `TableController`, feed `rows.length` as the virtualizer count inside `render()`, and render only `virtualizer.getVirtualItems()` with each row absolutely positioned via `transform: translateY(...)`. Routing keywords: lit-virtual, VirtualizerController, virtualization, virtualized-rows, lit table.
type	composition
library	tanstack-table
framework	lit
library_version	9.0.0-alpha.48
requires	["lit/table-state","row-expanding"]
sources	["TanStack/table:docs/guide/virtualization.md","TanStack/table:examples/lit/virtualized-rows/src/main.ts","TanStack/table:examples/react/virtualized-rows/","TanStack/table:examples/react/virtualized-columns/"]

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.

TanStack Table is headless — it does not virtualize rows or columns. For long lists, pair the table with @tanstack/lit-virtual, which ships VirtualizerController — a ReactiveController like TableController.

Install

npm install @tanstack/lit-table @tanstack/lit-virtual

The Pattern (Row Virtualization)

1. Build the table with TableController as usual.
2. Construct a VirtualizerController(host, opts) once. Capture a Ref for the scroll element.
3. Inside render(), get rows = table.getRowModel().rows, then call virtualizer.setOptions({ ..., count: rows.length }).
4. Render only virtualizer.getVirtualItems(). Each virtual row is absolutely positioned via transform: translateY(${item.start}px).
5. Attach ref on each row to call virtualizer.measureElement(...) for dynamic sizing.

import { LitElement, html } from 'lit'
import { customElement, state } from 'lit/decorators.js'
import { repeat } from 'lit/directives/repeat.js'
import { styleMap } from 'lit/directives/style-map.js'
import { Ref, createRef, ref } from 'lit/directives/ref.js'
import { VirtualizerController } from '@tanstack/lit-virtual'
import {
  FlexRender,
  TableController,
  columnSizingFeature,
  createSortedRowModel,
  rowSortingFeature,
  sortFns,
  tableFeatures,
  type ColumnDef,
} from '@tanstack/lit-table'

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

const columns: Array<ColumnDef<typeof features, Person>> = [
  { accessorKey: 'id', header: 'ID', size: 60 },
  {
    accessorKey: 'firstName',
    header: 'First',
    cell: (info) => info.getValue(),
  },
  // …
]

@customElement('virtualized-table')
class VirtualizedTable extends LitElement {
  @state()
  private _data: Person[] = makeData(50_000)

  private tableController = new TableController<typeof features, Person>(this)
  private rowVirtualizerController!: VirtualizerController<Element, Element>
  private tableContainerRef: Ref = createRef()

  connectedCallback() {
    this.rowVirtualizerController = new VirtualizerController(this, {
      count: this._data.length,
      getScrollElement: () => this.tableContainerRef.value!,
      estimateSize: () => 33,
      overscan: 5,
    })
    super.connectedCallback()
  }

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

    const { rows } = table.getRowModel()

    // Sync the virtualizer count with the post-feature rows.
    const virtualizer = this.rowVirtualizerController.getVirtualizer()
    virtualizer.setOptions({ ...virtualizer.options, count: rows.length })

    return html`
      <div
        ${ref(this.tableContainerRef)}
        style="${styleMap({
          overflow: 'auto',
          position: 'relative',
          height: '800px',
        })}"
      >
        <table style="display: grid">
          <thead
            style="${styleMap({
              display: 'grid',
              position: 'sticky',
              top: 0,
              zIndex: 1,
            })}"
          >
            ${repeat(
              table.getHeaderGroups(),
              (hg) => hg.id,
              (hg) => html`
                <tr style="${styleMap({ display: 'flex', width: '100%' })}">
                  ${repeat(
                    hg.headers,
                    (h) => h.id,
                    (h) => html`
                      <th
                        style="${styleMap({
                          display: 'flex',
                          width: `${h.getSize()}px`,
                        })}"
                        @click="${h.column.getToggleSortingHandler()}"
                      >
                        ${FlexRender({ header: h })}
                      </th>
                    `,
                  )}
                </tr>
              `,
            )}
          </thead>
          <tbody
            style="${styleMap({
              display: 'grid',
              height: `${virtualizer.getTotalSize()}px`,
              position: 'relative',
            })}"
          >
            ${repeat(
              virtualizer.getVirtualItems(),
              (item) => item.key,
              (item) => {
                const row = rows[item.index]
                return html`
                  <tr
                    style="${styleMap({
                      display: 'flex',
                      position: 'absolute',
                      transform: `translateY(${item.start}px)`,
                      width: '100%',
                    })}"
                    ${ref((node) => virtualizer.measureElement(node ?? null))}
                  >
                    ${repeat(
                      row.getAllCells(),
                      (c) => c.id,
                      (cell) => html`
                        <td
                          style="${styleMap({
                            display: 'flex',
                            width: `${cell.column.getSize()}px`,
                          })}"
                        >
                          ${FlexRender({ cell })}
                        </td>
                      `,
                    )}
                  </tr>
                `
              },
            )}
          </tbody>
        </table>
      </div>
    `
  }
}

Source: examples/lit/virtualized-rows/src/main.ts.

Column Virtualization

Same shape, but the virtualizer's count is columns.length (or visible columns) and you index visible columns inside each row. Useful for wide kitchen-sink tables. The horizontal virtualizer's options include horizontal: true.

With Pagination / Filtering

Always use table.getRowModel().rows.length as the count — that's the post-feature row array (sorted, filtered, paginated). The virtualizer should never wrap the raw data array.

With @tanstack/lit-table's subscribe

subscribe is an async Lit directive that enables fine-grained reactivity by updating only when the selected part of the store or atom changes. Rather than triggering a full re-render whenever the table state updates, you can use subscribe to watch specific slices of state and update only the affected parts of the template. This reduces unnecessary renders and improves performance for large tables or complex UI hierarchies. Source: packages/lit-table/src/subscribe-directive.ts.

Common Mistakes

CRITICAL Reimplementing virtualization by hand

Wrong: manual slicing + intersection observers + per-row offset math.

Correct: use @tanstack/lit-virtual's VirtualizerController. It handles measurement, overscan, scroll alignment, and dynamic sizing. Source: docs/guide/virtualization.md.

HIGH Using the wrong row source

Wrong:

new VirtualizerController(this, { count: this._data.length /* … */ })

Correct:

const { rows } = table.getRowModel()
virtualizer.setOptions({ ...virtualizer.options, count: rows.length })

Always count post-feature rows, not raw data. Source: examples/lit/virtualized-rows/src/main.ts.

HIGH Constructing VirtualizerController inside render()

Wrong: new controller per frame.

Correct: construct once (typically in connectedCallback) and call setOptions per render to sync count. Source: examples/lit/virtualized-rows/src/main.ts (lines 77–85).

HIGH Forgetting position: relative on the scroll parent / position: absolute on rows

Wrong: rows stack at the top because there's no positioned ancestor with the total height.

Correct: scroll parent uses position: relative, <tbody> uses height: virtualizer.getTotalSize() + 'px', each row uses position: absolute + transform: translateY(...).

MEDIUM Mixing virtualization with manualPagination

You usually don't need both. Server pagination already limits the row count. Virtualize when the client holds the full dataset.

See Also

• tanstack-table/lit/table-state — Subscribe for fine-grained re-renders.
• tanstack-table/lit/lit-table-controller — controller lifecycle.
• tanstack-table/row-expanding — virtualizing rows with sub-component rows requires variable height + measureElement.