TanStack Table

TanStack Table V9 introduces significant architectural changes compared to V8, focusing on performance, type-safety, and composability. While the core headless model, column definitions (accessorKey, accessorFn, header, cell, footer), and rendering patterns remain familiar, the underlying state management and feature registration systems have been overhauled.

Key Changes in V9:

• State Management: Moved from V8 writable-store patterns to a foundation of TanStack Store atoms and Svelte 5 runes.
• Feature-Based Architecture: Features (like sorting, filtering, or pagination) must be explicitly registered. This enables better tree-shaking, as unused feature code is not included in your bundle.
• Type-Safety: Replaces global declaration merging with per-table meta types (tableMeta, columnMeta, filterMeta).
• Performance: Improved memory usage (up to 90% savings in large tables) and faster client-side row models (40-70% speed improvements).
• Modern Builds: The library is now ESM-only and targets ES2022.

The TanStack Table API is composed of a wide range of interfaces that define the structure and behavior of the table, its columns, rows, cells, and headers. These interfaces are categorized by their functional area:

• Core Table & State: Interfaces like Table_Table, TableOptions_Table, and various TableState_* interfaces define the central table instance and its configuration.
• Columns: Interfaces such as Column_Column, ColumnDef_*, and ColumnPinningState manage column definitions, visibility, resizing, and ordering.
• Rows & Cells: Interfaces like Row_Row, Cell_Cell, and Row_RowSelection handle data rows, cell-level interactions (selection, spanning), and row-level features (expanding, pinning).
• Headers: Interfaces like Header_Header and HeaderGroup manage the visual and logical structure of the table header.
• Aggregation: Interfaces such as AggregationFnDef and AggregationValueContext provide tools for summarizing data.
• Row Models: Various CachedRowModel_* interfaces define how data is presented after filtering, sorting, or pagination.
• Filtering & Sorting: Interfaces like FilterFn and SortFn define the logic for data manipulation.

Faceting is a mechanism used to derive metadata for building filtering interfaces (like checkboxes, sliders, or autocomplete menus). It answers questions about the available data such as:

• Which values are available in a column?
• How often does each value occur (counts)?
• What are the minimum and maximum values in a numeric range?
• Which rows should be used for custom facet calculations?

Key Distinctions:

• Faceting vs. Filtering: Filtering determines which rows remain in the table. Faceting provides the choices for those filters. A facet shows available options based on other active filters, allowing users to see what other options exist even after they have selected a value in the current column.
• Faceting vs. Row Aggregation: Row aggregation (like sum or average) computes summary values for display in footers or grouped rows. Faceting produces metadata specifically for filter controls and does not use a column's aggregationFn.

Faceting derives metadata used to build filtering interfaces (e.g., available values, occurrence counts, or numeric ranges). It answers: "Which filtering choices remain?"

Key Distinctions:

• Faceting vs. Filtering: Filtering determines which rows remain in the table. Faceting provides the values/counts used to build the UI that performs the filtering.
• Faceting vs. Row Aggregation: Aggregation computes summary values (sum, average) for display in footers or grouped rows. Faceting produces metadata for filter controls. Faceted counts do not use a column's aggregationFn and do not create aggregate rows.
• Reactive Behavior: A column's faceted model includes rows that pass every active filter except that column's own filter. This allows a user to see alternative options in a facet even after they have selected a value for it, while still allowing other facets to narrow the results.

To access the table state or methods in child components, use the useTableContext hook provided by your factory. For this to work, the child components must be wrapped in the corresponding provider (e.g., table.AppTable).

AppTable can be used in two ways:

1. Standard usage: Pass ordinary JSX children. The children will have access to the table context.
2. Selector usage: Pass a selector function and a function as children. The function child will receive the specific slice of state returned by the selector.

// 1. Standard usage with useTableContext
function RowCount() {
  const table = useTableContext()
  return <output>{table.getRowModel().rows.length}</output>
}

function MyTable({ data, columns }) {
  const table = useAppTable({ data, columns })
  return (
    <table.AppTable>
      <RowCount />
    </table.AppTable>
  )
}

// 2. Selector usage for specific state slices
<table.AppTable selector={(state) => state.rowSelection}>
  {(rowSelection) => <output>{Object.keys(rowSelection).length}</output>}
</table.AppTable>