tanstack-table

TanStack Table

概要

TanStack Table はヘッドレステーブルライブラリです。状態管理とロジックを提供しますが、UI は提供しません。描画は独自に実装し、並べ替え、フィルタリング、ページネーション、選択などは TanStack Table が処理します。

使用する場面： 並べ替え、フィルタリング、ページネーションに対応した複雑なデータテーブル、サーバーサイドのデータ、大規模なデータセット（仮想化を使用した 1000 行以上のデータ）、行の選択／展開／グループ化。

使用しない場面： シンプルな静的テーブル（<table> を直接使用）、表示のみのリスト（リストコンポーネントを使用）、スプレッドシートのような編集（AG Grid を検討）。

クイックリファレンス

パターン	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	グループカラムは固定しない（既知のバグ）
行の展開	getExpandedRowModel() + getSubRows	ネスト／ツリー構造のデータに使用
カラムのリサイズ	enableColumnResizing + columnResizeMode	リアルタイム更新には onChange、パフォーマンス重視には onEnd
行のグループ化	getGroupedRowModel() + aggregationFn	10k 行以上ではパフォーマンスが低下する
サーバーサイド	manual*: true フラグ + state を queryKey に含める	適切に再取得するため、すべての state をクエリキーに含める
無限スクロール	useInfiniteQuery + ページの平坦化	最適なパフォーマンスを得るには TanStack Virtual と組み合わせる
仮想化	@tanstack/react-virtual の useVirtualizer	コンテナが非表示の場合（タブ／モーダル）は無効にする
React 19 Compiler	'use no memo' ディレクティブ	v9 でコンパイラーとの互換性が修正されるまでは必須

よく使う操作

タスク	メソッド
カラムを並べ替える	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()

行モデル

インポート	用途
getCoreRowModel	必須
getSortedRowModel	並べ替え
getFilteredRowModel	フィルタリング
getPaginationRowModel	ページネーション
getExpandedRowModel	展開
getGroupedRowModel	グループ化
getFacetedRowModel	ファセットフィルターの件数
getFacetedUniqueValues	ファセットごとの一意な値
getFacetedMinMaxValues	ファセットごとの最小値／最大値

よくある間違い

間違い	正しいパターン
data／columns の参照が不安定	useMemo でメモ化するか、コンポーネントの外で定義する
サーバーサイド用の manual* フラグがない	manualPagination、manualSorting、manualFiltering を設定する
クエリキーにテーブルの状態がない	pagination、sorting、filters を queryKey に含める
@tanstack/table-core からインポートする	@tanstack/react-table からインポートする
v7 の useTable／Header／accessor を使用する	v8 の useReactTable／header／accessorKey を使用する
グループ列を固定する	親列ではなく、グループ内の個々の列を固定する
1 万件以上の行をグループ化する	サーバーサイドでグループ化するか、大規模なデータセットでは無効にする
ページ変更時に列フィルターがクリアされない	フィルター変更時に pageIndex を 0 にリセットする
React Compiler で 'use no memo' がない	useReactTable を使用するコンポーネントにディレクティブを追加する
行選択で getRowId がない	選択キーを安定させるため、getRowId: (row) => row.id を設定する
フィルター値の型が一致しない	値の型を一致させ、null ではなく undefined でクリアする

委任

• テーブルパターンの調査：Explore エージェントを使用
• サーバー統合のレビュー：Task エージェントを使用
• コードレビュー：code-reviewer エージェントに委任

tanstack-query スキルが利用できる場合は、データ取得、キャッシュ、無限クエリのパターンをそのスキルに委任してください。 tanstack-virtual スキルが利用できる場合は、単独での仮想化パターンをそのスキルに委任してください。 tanstack-router スキルが利用できる場合は、サーバーサイドのテーブル状態に関する URL 検索パラメーターの同期をそのスキルに委任してください。 tanstack-start スキルが利用できる場合は、サーバーサイドのデータ読み込み用サーバー関数をそのスキルに委任してください。

参考資料

• 列定義、ヘルパー、表示設定、選択
• フィルタリング：列、グローバル、ファジー、ファセット
• TanStack Query を使ったサーバーサイドのパターン
• カーソルページネーションによる無限スクロール
• 再利用可能なテーブルコンポーネント（Shadcn スタイル）
• 大規模なデータセット向けの仮想化
• 列と行の固定
• 行の展開とグループ化
• 既知の問題と解決策（15 件を記載）
• v7 から v8 への移行ガイド