Chapter 12: Table Instance Guide

Core Idea

The "table instance" (the table object returned by useTable/createTable/injectTable/constructTable) is not a <table> element — it's the single coordinating object for all table state and APIs; everything you read or mutate about the table goes through it.

Key Concepts

• Three required options to create a table: columns, data, features (from tableFeatures()). The core row model is always included; extra row model factories (filtering, sorting, pagination, ...) live as slots inside tableFeatures().
• Every framework adapter's creation function takes the same three core options, just with framework-idiomatic reactivity: React/Preact/Vue/Ember use useTable({ features, columns, data }); Solid/Svelte/Alpine use createTable({ features, columns, get data() { return data() } }) (a getter, for reactivity); Angular uses injectTable(() => ({ features, columns, data: this.data() })); Lit uses a TableController; raw @tanstack/table-core uses constructTable and needs an explicit coreReactivityFeature if you want reactivity outside a framework adapter.
• State is TanStack Store atoms under the hood. Each registered feature owns the state slices it needs (e.g. rowSelectionFeature → rowSelection state, rowPaginationFeature → pagination state). table.baseAtoms are the internal writable atoms; table.atoms are the public readonly atoms per slice; table.store is a readonly flat snapshot derived from table.atoms.
• Reading/writing follows a consistent shape per feature: table.atoms.rowSelection.get() or table.store.state.rowSelection to read, table.set<Feature>(updater) to write, table.reset<Feature>() to reset to initialState.
• Table APIs (dozens of them, one set per registered feature) are how you read/mutate everything else — full signatures live in the API reference chapters, not duplicated in guides.
• Row models are a distinct concept: a special table API surface (table.getRowModel(), table.getPreFilteredRowModel(), etc.) for reading rows back out, which can differ significantly from the raw data array once filtering/sorting/grouping/expansion are applied (see Row Models Guide).

Code Examples

const features = tableFeatures({}) // core only
const table = useTable({ features, columns, data })

table.atoms.rowSelection.get()          // current row selection (atom read)
table.store.state.rowSelection          // current row selection (store snapshot)
table.setRowSelection((old) => ({ ...old, '0': true }))
table.resetRowSelection()

• What it demonstrates: the same read/write/reset triad every feature's state follows — learn it once on rowSelection, reuse it for sorting, pagination, columnFilters, etc.

Key Takeaways

1. Treat table as the one source of truth — don't reach past it into data/columns directly once the table is built; row models and column objects are the derived, correct views.
2. State reads have two flavors: table.atoms.<slice>.get() (single atom) and table.store.state.<slice> (flat snapshot) — framework adapters layer their own reactive access on top (see Table State Guide) for actual re-render-triggering reads.
3. constructTable (raw @tanstack/table-core, no framework adapter) needs an explicit coreReactivityFeature if you want the table to be reactive at all — every official adapter wires this for you.

Connects To

• Table State (React) Guide: the framework-reactive way to read/subscribe to this same state.
• Row Models Guide: how table.getRowModel() and friends differ from raw data.
• Core Table Types (API reference): Table, TableOptions, TableState full signatures.