Back to Details

tanstack-table

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TanStack Table

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).
TanStack Table是一个无头表格库——它提供状态管理和逻辑，但不提供UI。由你负责渲染部分，它则处理排序、筛选、分页、选择等功能。
适用场景： 包含排序/筛选/分页的复杂数据表格、服务端数据、大型数据集（1000+行，搭配虚拟化）、行选择/展开/分组。
不适用场景： 简单静态表格（直接使用
<table>
标签）、仅用于展示的列表（使用列表组件）、类电子表格的编辑功能（考虑使用AG Grid）。

Quick Reference

快速参考

PatternAPI / ConfigKey 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
模式API/配置关键要点
基础表格
useReactTable({ data, columns, getCoreRowModel })
对data和columns进行记忆化处理以避免重渲染
列辅助工具
createColumnHelper<T>()
类型安全的列定义
列分组
columnHelper.group({ header, columns })
嵌套表头；不要固定分组列
排序
getSortedRowModel()
+ 
onSortingChange
服务端场景需设置
manualSorting: true
筛选
getFilteredRowModel()
+ 
onColumnFiltersChange
服务端场景需设置
manualFiltering: true
分页
getPaginationRowModel()
+ 
onPaginationChange
服务端场景需设置
manualPagination: true
+ 
pageCount
行选择
enableRowSelection
+ 
onRowSelectionChange
设置
getRowId
以确保选择键的稳定性
列可见性
onColumnVisibilityChange
使用
column.toggleVisibility()
切换显示状态
列固定
enableColumnPinning
+ 
initialState.columnPinning
不要固定分组列（已知bug）
行展开
getExpandedRowModel()
+ 
getSubRows
适用于嵌套/树形数据
列调整大小
enableColumnResizing
+ 
columnResizeMode
实时调整用
onChange
，高性能调整用
onEnd
行分组
getGroupedRowModel()
+ 
aggregationFn
数据量达10k+行时性能会下降
服务端
manual*: true
标记 + 在queryKey中包含状态		将所有状态纳入queryKey以确保正确重新获取数据
无限滚动
useInfiniteQuery
+ 扁平化页面数据		搭配TanStack Virtual使用可获得最佳性能
虚拟化
useVirtualizer
from 
@tanstack/react-virtual
容器隐藏时（如标签页/模态框）需禁用该功能
React 19 Compiler
'use no memo'
指令		在v9版本修复兼容性问题前必须添加该指令

Common Operations

常用操作

TaskMethod
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()
操作任务实现方法
排序列
column.toggleSorting()
筛选列
column.setFilterValue(value)
跳转到第一页
table.firstPage()
下一页
table.nextPage()
上一页
table.previousPage()
跳转到最后一页
table.lastPage()
跳转到指定页
table.setPageIndex(n)
选择行
row.toggleSelected()
隐藏列
column.toggleVisibility()
获取原始数据
row.original
固定列
column.pin('left')
调整列大小
header.getResizeHandler()
展开行
row.toggleExpanded()

Row Models

行模型

ImportPurpose
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
导入项用途
getCoreRowModel
必填项
getSortedRowModel
排序功能
getFilteredRowModel
筛选功能
getPaginationRowModel
分页功能
getExpandedRowModel
行展开功能
getGroupedRowModel
行分组功能
getFacetedRowModel
分面筛选计数
getFacetedUniqueValues
分面下的唯一值
getFacetedMinMaxValues
分面下的极值

Common Mistakes

常见错误

MistakeCorrect Pattern
Unstable data/columns referenceMemoize with 
useMemo
or define outside component
Missing 
manual*
flags for server-side		Set 
manualPagination
, 
manualSorting
, 
manualFiltering
Query key missing table stateInclude 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 columnsPin individual columns within the group, not parent
Grouping on 10k+ rowsUse server-side grouping or disable for large datasets
Column filter not clearing on page changeReset 
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 mismatchMatch value types; clear with 
undefined
, not 
null
错误内容正确做法
不稳定的data/columns引用使用
useMemo
进行记忆化处理，或在组件外部定义
服务端场景缺少
manual*
标记		设置
manualPagination
、
manualSorting
、
manualFiltering
Query key中未包含表格状态将分页、排序、筛选状态纳入queryKey
从
@tanstack/table-core
导入		从
@tanstack/react-table
导入
使用v7版本的
useTable
/ 
Header
/ 
accessor
使用v8版本的
useReactTable
/ 
header
/ 
accessorKey
固定分组列固定分组内的单个列，而非父分组
对10k+行数据进行分组使用服务端分组，或针对大型数据集禁用该功能
分页切换时列筛选未清空筛选条件变化时将
pageIndex
重置为0
使用React Compiler时缺少
'use no memo'
指令		在使用
useReactTable
的组件中添加该指令
行选择功能缺少
getRowId
配置		设置
getRowId: (row) => row.id
以确保选择键的稳定性
筛选值类型不匹配匹配值类型；使用
undefined
而非
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.
  • 表格模式探索：使用
    Explore
    Agent
  • 服务端集成评审：使用
    Task
    Agent
  • 代码评审：委托给
    code-reviewer
    Agent
如果
tanstack-query
技能可用，可将数据获取、缓存和无限查询模式的相关任务委托给它。 如果
tanstack-virtual
技能可用，可将独立虚拟化模式的相关任务委托给它。 如果
tanstack-router
技能可用，可将服务端表格状态与URL搜索参数同步的任务委托给它。 如果
tanstack-start
技能可用，可将服务端数据加载的服务端函数相关任务委托给它。

References

参考资料

  • Column definitions, helpers, visibility, and selection
  • Filtering: column, global, fuzzy, and faceted
  • Server-side patterns with TanStack Query
  • Infinite scroll with cursor pagination
  • Reusable table components (Shadcn-styled)
  • Virtualization for large datasets
  • Column and row pinning
  • Row expanding and grouping
  • Known issues and solutions (15 documented)
  • v7 to v8 migration guide
  • 列定义、辅助工具、可见性与选择
  • 筛选：列筛选、全局筛选、模糊筛选与分面筛选
  • 基于TanStack Query的服务端模式
  • 基于游标分页的无限滚动
  • 可复用表格组件（Shadcn风格）
  • 大型数据集虚拟化
  • 列与行固定
  • 行展开与分组
  • 已知问题与解决方案（15种已记录）
  • v7到v8迁移指南