tanstack-table

TanStack Table

Use this skill when work touches TanStack Table v9, especially @tanstack/react-table, table feature composition, complex data-grid behavior, or migration from v8 APIs.

Workflow

1. Confirm the local version and target API before changing code:
   • @tanstack/react-table, @tanstack/table-core, optional @tanstack/react-table-devtools, optional @tanstack/react-store, optional @tanstack/react-virtual, and React version.
   • Whether the app is on stable v9 (latest is 9.2.x). Older apps may still pin v8; do not mix v8 and v9 APIs.
   • Current table creation style: useTable, createTableHook, stockFeatures, or temporary useLegacyTable.
   • Which features are registered in tableFeatures() and which row model factories are actually needed.
2. Refresh current docs for migrations, new feature APIs, or package mismatches. Start from source-map.md.
3. For installation, core setup, columns, rendering, and row models, use setup-core.md.
4. For v8-to-v9 migrations, useLegacyTable, state ownership, external atoms, selectors, table context, and React Compiler concerns, use state-and-migration.md.
5. For sorting, filtering, faceting, pagination, selection, pinning, sizing, grouping, aggregation, cell selection, and spanning, use features.md.
6. For server-side patterns, TanStack Query, virtualization, devtools, worker row models, performance, accessibility, and testing, use production-patterns.md.

Implementation Judgment

• Prefer useTable plus explicit tableFeatures() for one-off tables. Use createTableHook when multiple tables share features, defaults, or standardized components. Use stockFeatures only as a kitchen-sink shortcut when tree-shaking does not matter yet.
• Register only the features the table needs. The core row model is automatic; client-side filtering, sorting, grouping, expanding, faceting, and pagination need matching row model factories.
• Prefer individually imported filterFn_*, sortFn_*, and aggregationFn_* entries in registry slots. Full filterFns / sortFns / aggregationFns objects still work but bundle every built-in.
• Keep data, columns, and reusable column helpers stable across renders.
• Do not destructure methods from row, cell, column, or header instances. Call them on the instance.
• Use table.FlexRender or the v9 FlexRender component for cells and headers.
• Prefer external atoms for state that powers server queries, persistence, or cross-component UI. The classic state plus onXChange pattern remains useful for simple migration work.
• Use manualSorting, manualFiltering, manualPagination, and manualGrouping when the server already returns processed data. Keep all table operations consistent at the same data scope.
• v9 works with the React Compiler; drop v8 'use no memo' workarounds. Nested components that receive only stable row / cell / column / header objects must subscribe (Subscribe / useSelector) to the state they render.
• Treat useLegacyTable as a temporary migration bridge only. It bundles all features, keeps full-state subscriptions, and does not support the main v9 composability benefits.
• Column pinning uses logical start / end regions (not left / right). Aggregation is its own rowAggregationFeature, independent from columnGroupingFeature.

Verification

Prefer the repo's existing checks. For meaningful TanStack Table changes, include the relevant subset:

• Package/version check proving v9 APIs are available when used.
• Typecheck for feature registration, column definitions, state slices, and row model slots.
• Focused interaction tests for sorting, filtering, pagination, selection, cell selection, expansion, pinning, resizing, spanning, and server-query integration.
• Browser smoke for rendered markup, keyboard/focus behavior, sticky or virtualized layouts, and resize/scroll performance.
• Production build or profiling pass for large tables, virtualization, or column resizing changes.