TanStack Table
Overview
TanStack Table is a headless table library — it provides state management and logic but no UI. You supply the rendering; it handles sorting, filtering, pagination, selection, and more.
When to use: Complex data tables with sorting/filtering/pagination, server-side data, large datasets (1000+ rows with virtualization), row selection/expanding/grouping.
When NOT to use: Simple static tables (use <table> directly), display-only lists (use a list component), spreadsheet-like editing (consider AG Grid).
Quick Reference
| Pattern | API / Config | Key Points |
|---|
| Basic table | useReactTable({data, columns, getCoreRowModel}) | Memoize data/columns to prevent re-renders |
| Column helper | createColumnHelper<T>() | Type-safe column definitions |
| Column groups | columnHelper.group({header, columns}) | Nested headers; don't pin group columns |
| Sorting | getSortedRowModel() + onSortingChange | manualSorting: true for server-side |
| Filtering | getFilteredRowModel() + onColumnFiltersChange | manualFiltering: true for server-side |
| Pagination | getPaginationRowModel() + onPaginationChange | manualPagination: true + pageCount |
| Row selection | enableRowSelection + onRowSelectionChange | Set getRowId for stable selection keys |
| Column visibility | onColumnVisibilityChange | Toggle with column.toggleVisibility() |
| Column pinning | enableColumnPinning + initialState.columnPinning | Don't pin group columns (known bug) |
| Row expanding | getExpandedRowModel() + getSubRows | For nested/tree data |
| Column resizing | enableColumnResizing + columnResizeMode | onChange for live, onEnd for performant |
| Row grouping | getGroupedRowModel() + aggregationFn | Performance degrades at 10k+ rows |
| Server-side | manual*: true flags + include state in queryKey | All state in query key for proper refetching |
| Infinite scroll | useInfiniteQuery + flatten pages | Combine with TanStack Virtual for best perf |
| Virtualization | useVirtualizer from @tanstack/react-virtual | Disable when container hidden (tabs/modals) |
| React 19 Compiler | 'use no memo' directive | Required until v9 fixes compiler compat |
Common Operations
| Task | Method |
|---|
| Sort column | column.toggleSorting() |
| Filter column | column.setFilterValue(value) |
| First page | table.firstPage() |
| Next page | table.nextPage() |
| Previous page | table.previousPage() |
| Last page | table.lastPage() |
| Go to page | table.setPageIndex(n) |
| Select row | row.toggleSelected() |
| Hide column | column.toggleVisibility() |
| Get original data | row.original |
| Pin column | column.pin('left') |
| Resize column | header.getResizeHandler() |
| Expand row | row.toggleExpanded() |
Row Models
| Import | Purpose |
|---|
getCoreRowModel | Required |
getSortedRowModel | Sorting |
getFilteredRowModel | Filtering |
getPaginationRowModel | Pagination |
getExpandedRowModel | Expanding |
getGroupedRowModel | Grouping |
getFacetedRowModel | Faceted filter counts |
getFacetedUniqueValues | Unique values per facet |
getFacetedMinMaxValues | Min/max per facet |
Common Mistakes
| Mistake | Correct Pattern |
|---|
| Unstable data/columns reference | Memoize with useMemo or define outside component |
Missing manual* flags for server-side | Set manualPagination, manualSorting, manualFiltering |
| Query key missing table state | Include pagination, sorting, filters in queryKey |
Import from @tanstack/table-core | Import from @tanstack/react-table |
Using v7 useTable / Header / accessor | Use v8 useReactTable / header / accessorKey |
| Pinning group columns | Pin individual columns within the group, not parent |
| Grouping on 10k+ rows | Use server-side grouping or disable for large datasets |
| Column filter not clearing on page change | Reset pageIndex to 0 when filters change |
Missing 'use no memo' with React Compiler | Add directive to components using useReactTable |
Missing getRowId with row selection | Set getRowId: (row) => row.id for stable selection keys |
| Filter value type mismatch | Match value types; clear with undefined, not null |
Delegation
- Table pattern discovery: Use
Explore agent - Server integration review: Use
Task agent - Code review: Delegate to
code-reviewer agent
If the tanstack-query skill is available, delegate data fetching, caching, and infinite query patterns to it. If the tanstack-virtual skill is available, delegate standalone virtualization patterns to it. If the tanstack-router skill is available, delegate URL search param sync for server-side table state to it. If the tanstack-start skill is available, delegate server functions for server-side data loading to it.
References
