--- name: table-state description: > Read, select, subscribe to, and control React Table v9 state with useTable selectors, table.state, table.Subscribe, table.atoms, table.store, and external TanStack Store atoms. Load for controlled state, render performance, or React Compiler builder-method subscription problems. metadata: type: framework library: '@tanstack/react-table' library_version: '9.0.0' framework: react requires: - '@tanstack/table-core#core' - getting-started sources: - 'TanStack/table:docs/framework/react/guide/table-state.md' - 'TanStack/table:examples/react/basic-subscribe' - 'TanStack/table:packages/react-table/src/Subscribe.ts' - 'TanStack/table:packages/react-table/src/useTable.ts' --- This skill builds on `@tanstack/table-core#core` and `getting-started`. Read them first for table construction and feature-owned state. ## State Mental Model TanStack Table is primarily a state coordinator. Keep state internal unless another subsystem needs to read, persist, validate, or drive it. With no `initialState`, `atoms`, `state`, or `on[State]Change` options, the table owns all registered slices. - `table.baseAtoms` are the internal writable atoms initialized from resolved initial state. - `table.atoms` are readonly derived atoms for the active owner of each registered slice. - `table.store` combines those atoms into one readonly flat store. - `table.state` is only the value selected by the second `useTable` argument. State is feature-based. Registering `rowPaginationFeature` creates pagination state and APIs; without it, `pagination` must not exist in `initialState`, `state`, `atoms`, `table.atoms`, `table.store`, or `table.state`. Treat a missing state API as a likely missing feature import, not a typing problem. Keep `features`, `data`, and `columns` stable. State subscriptions do not compensate for new model-input references on every render. ## Setup ```tsx import { rowSelectionFeature, tableFeatures, useTable, } from '@tanstack/react-table' const features = tableFeatures({ rowSelectionFeature }) export function SelectionCount({ data, columns, }: { data: Array<{ id: string }> columns: any[] }) { const table = useTable({ features, data, columns }, (state) => ({ rowSelection: state.rowSelection, })) return <output>{Object.keys(table.state.rowSelection).length}</output> } ``` The optional selector controls which state changes rerender the component and which selected fields appear on `table.state`. Omitting it selects all registered slices. ## Core Patterns ### Subscribe at the expensive boundary ```tsx function SelectedRows({ table, }: { table: ReturnType<typeof useTable<typeof features, { id: string }>> }) { return ( <table.Subscribe selector={(state) => state.rowSelection}> {(rowSelection) => <output>{Object.keys(rowSelection).length}</output>} </table.Subscribe> ) } ``` At a top-level component holding the adapter's table instance, `table.Subscribe` selects from `table.store`. Use this after measuring or when React Compiler cannot see state reads hidden behind table builder methods. ### Control a slice with an external atom ```tsx import { useCreateAtom } from '@tanstack/react-store' const selection = useCreateAtom<Record<string, boolean>>({}) const table = useTable({ features, columns, data, atoms: { rowSelection: selection }, }) ``` An external atom is both ownership and subscription source; it avoids value-or-updater glue. ### Control a slice with React state ```tsx const [rowSelection, setRowSelection] = useState<Record<string, boolean>>({}) const table = useTable({ features, columns, data, state: { rowSelection }, onRowSelectionChange: setRowSelection, }) ``` ## Choose State Ownership Choose exactly one owner for each slice: 1. Use internal state by default and call feature APIs such as `table.setSorting`, `table.nextPage`, `column.toggleVisibility`, or `row.toggleSelected`. 2. Use `initialState.<slice>` only to set the starting and reset value. Changing `initialState` later does not reset the table. 3. Prefer a stable external atom in `atoms.<slice>` when Table, Query, routing, or another component must share the slice. Table APIs write that atom directly; do not also add `on[State]Change`. 4. Use `state.<slice>` plus its matching `on[State]Change` for simple React-controlled state or v8-style integrations. Always resolve both raw values and updater functions. External atoms take precedence over external `state`; external `state` synchronizes into the internal base atom. Do not declare the same slice in multiple ownership options and rely on precedence as application logic. The global v8 `onStateChange` callback is gone in v9; control slices individually or subscribe to `table.store` to observe all state. ## Initialize, Update, and Reset Prefer feature methods over direct atom writes because feature methods preserve related behavior. `table.baseAtoms.pagination.set(...)` is a low-level escape hatch only for internally owned state; write the supplied external atom when `atoms.pagination` owns the slice. Feature reset methods reset to `table.initialState` by default: ```tsx table.resetSorting() table.resetPagination() table.resetPagination(true) // feature blank/default state ``` Slice reset methods flow through that feature's updater and can update an external owner. Core `table.reset()` resets internal base atoms, so it is not the primary reset mechanism for externally owned atoms. Use feature-specific types for owned slices and infer the full state from the feature set: ```tsx import type { PaginationState, TableState } from '@tanstack/react-table' type AppTableState = TableState<typeof features> const initialPagination: PaginationState = { pageIndex: 0, pageSize: 20 } ``` ## Common Mistakes ### HIGH Treating a snapshot as subscription Wrong: ```tsx const count = Object.keys(table.atoms.rowSelection.get()).length ``` Correct: ```tsx const count = Object.keys(table.state.rowSelection).length ``` `atoms.*.get()` and `table.store.state` return current values but do not subscribe a React render. Source: `packages/react-table/src/useTable.ts` ### HIGH Supplying only the change callback Wrong: ```tsx const table = useTable({ features, columns, data, onRowSelectionChange: setRowSelection, }) ``` Correct: ```tsx const table = useTable({ features, columns, data, state: { rowSelection }, onRowSelectionChange: setRowSelection, }) ``` Once a callback takes ownership, the corresponding controlled value must be written back. Source: `docs/framework/react/guide/table-state.md` ### HIGH Hiding builder reads from React Compiler Wrong: ```tsx const SelectionCell = memo(({ row }) => ( <input type="checkbox" checked={row.getIsSelected()} onChange={row.getToggleSelectedHandler()} /> )) ``` Correct: ```tsx import { Subscribe } from '@tanstack/react-table' const SelectionCell = memo(({ row }) => ( <Subscribe source={row.table.atoms.rowSelection} selector={(selection) => selection[row.id]} > {(selected) => ( <input type="checkbox" checked={!!selected} onChange={row.getToggleSelectedHandler()} /> )} </Subscribe> )) ``` `useTable` already returns a fresh table reference on state changes. The remaining hazard is a nested component receiving a stable row, cell, column, or header and hiding a state read behind its methods. Inside cell and header render contexts, `table` is typed as core `Table`, so import standalone `Subscribe`; use `source={table.store}` with a selector for multiple slices, or a specific atom for the narrowest boundary. Source: `docs/framework/react/guide/table-state.md` ### MEDIUM Optimizing every cell preemptively Wrong: ```tsx <table.Subscribe source={table.atoms.rowSelection}> {() => <Cell cell={cell} />} </table.Subscribe> ``` Correct: ```tsx <Cell cell={cell} /> ``` Default `useTable` state selection is the simpler starting point; introduce fine-grained boundaries where measurement or compiler behavior justifies them. Source: `docs/framework/react/guide/table-state.md` ## API Discovery Inspect `node_modules/@tanstack/react-table/dist/useTable.d.ts` and `Subscribe.d.ts`. Core atom precedence and state slices live under `node_modules/@tanstack/table-core/dist/`.