ReactとTanStack Tableで、表示する列をチェックボックスで選ぶ方法
TanStack Table v9 では、columnVisibilityFeature を登録し、列ごとのチェックボックスに column.getToggleVisibilityHandler() を渡すと、チェックを外した列が表から消えます。管理画面の一覧表で、列が多すぎて横にはみ出すときに、利用者が見たい列だけを選べるようにする(列の表示・非表示を切り替える)場面で使えるやり方です。
検証環境で5列の表を作り、チェックボックスを操作するたびに、表示の状態(columnVisibility)と表の見出し・セルがどう変わるかを記録しました。
検証環境は Ubuntu 24.04、Node.js 22.23.4 です。使ったのは @tanstack/react-table 9.3.1(中で使われる @tanstack/table-core も 9.3.1)、react / react-dom 19.3.1、@types/react / @types/react-dom 19.3.0、typescript 7.0.2、esbuild 0.28.2 です。.tsx を tsc で型チェックしてから esbuild で本番用にビルドし、Playwright 1.63.0 の Chromium で動かしました。StrictMode では包んでいません。
TanStack Table v8 の書き方、公式ガイドがすすめる外部の atom で状態を持つ書き方、選んだ列をブラウザに保存すること、列のグループ(2段の見出し)、列の固定や並べ替えとの組み合わせ、スクリーンリーダーでの読み上げは、この記事では試していません。
v9 では columnVisibilityFeature を登録してから使う
インストールするのは @tanstack/react-table です。インストールの説明では、React 18 以降で動くとされています。
npm install @tanstack/react-table
v9 では、表を useTable で作り、使う機能を tableFeatures() で登録します。列の表示・非表示は columnVisibilityFeature です。列の表示・非表示のガイドに、これを features に加えると関係する API が使えるようになると書かれています。
tableFeatures({}) のように機能を登録しないで作った表で column.getIsVisible() を呼ぶと、型チェックの段階でエラーになりました。
nofeature/src/NoFeature.tsx(16,44): error TS2339: Property 'getIsVisible' does not exist on type 'Column_Core<{}, Cat, unknown>'.
nofeature/src/NoFeature.tsx(16,77): error TS2339: Property 'getToggleVisibilityHandler' does not exist on type 'Column_Core<{}, Cat, unknown>'.
列の定義に、チェックボックスの横に出す名前を用意する
表に出すのは、猫の名前、年齢、体重、毛の色、ひとことの5列です。データは3行にしました。
export type Cat = { name: string; age: number; weight: number; color: string; memo: string };
export const cats: Cat[] = [
{ name: 'たま', age: 3, weight: 4.2, color: '茶トラ', memo: '窓辺が好き' },
{ name: 'ミケ', age: 5, weight: 3.8, color: '三毛', memo: '人見知り' },
{ name: 'クロ', age: 8, weight: 4.6, color: '黒', memo: '夜に元気' },
];
チェックボックスの横には、列の名前を出します。ガイドの注意書きによると、列の定義の header は文字列のほかに JSX や関数のこともあり、見出しを描くための情報(header context)がないと描けない場合があります。隠した列にはその情報がないこともあるため、列の ID をキーにした名前の対応表などを使うようにすすめられています。ここでは対応表を作り、見出しにも同じ名前を使いました。
import { columnVisibilityFeature, createColumnHelper, tableFeatures } from '@tanstack/react-table';
import type { Cat } from './cats';
// 列の表示・非表示の機能を登録する
export const features = tableFeatures({ columnVisibilityFeature });
// チェックボックスの横に出す名前(見出しにも使う)
export const columnLabels: Record<string, string> = {
name: '名前',
age: '年齢',
weight: '体重(kg)',
color: '毛の色',
memo: 'ひとこと',
};
const columnHelper = createColumnHelper<typeof features, Cat>();
export const columns = columnHelper.columns([
// 名前の列は隠せないようにする
columnHelper.accessor('name', { header: columnLabels.name, enableHiding: false }),
columnHelper.accessor('age', { header: columnLabels.age }),
columnHelper.accessor('weight', { header: columnLabels.weight }),
columnHelper.accessor('color', { header: columnLabels.color }),
columnHelper.accessor('memo', { header: columnLabels.memo }),
]);
「名前」の列には enableHiding: false を付けました。どの猫の行かがいつでも分かるように、この列だけは隠せないようにしています。
チェックボックスと表のコンポーネント
表示の状態は useState で持ち、state.columnVisibility と onColumnVisibilityChange で useTable に渡しました。ガイドでは v8 と同じこの書き方も使えるとしたうえで、v9 では外部の atom(TanStack Store の状態の入れ物)を atoms に渡す書き方をすすめています。この記事では、状態の中身を確かめやすい useState の書き方にしました。
import { useState } from 'react';
import { useTable, type ColumnVisibilityState } from '@tanstack/react-table';
import { cats } from './cats';
import { columnLabels, columns, features } from './columns';
// チェックボックスで、表示する列を選べる表
export function CatTable() {
// 最初は「ひとこと」の列を隠しておく
const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>({
memo: false,
});
const table = useTable({
features,
columns,
data: cats,
state: { columnVisibility },
onColumnVisibilityChange: setColumnVisibility,
});
const allVisible = table.getIsAllColumnsVisible();
// 「すべて」の途中の状態は、隠せる列だけで判断する
const someVisible = table
.getAllLeafColumns()
.some((column) => column.getCanHide() && column.getIsVisible());
return (
<>
<fieldset>
<legend>表示する列</legend>
<label>
<input
type="checkbox"
checked={allVisible}
ref={(el) => {
if (el) el.indeterminate = someVisible && !allVisible;
}}
onChange={table.getToggleAllColumnsVisibilityHandler()}
/>
すべて
</label>
{table.getAllLeafColumns().map((column) => (
<label key={column.id}>
<input
type="checkbox"
checked={column.getIsVisible()}
disabled={!column.getCanHide()}
onChange={column.getToggleVisibilityHandler()}
/>
{columnLabels[column.id] ?? column.id}
</label>
))}
</fieldset>
<table>
<thead>
{table.getHeaderGroups().map((headerGroup) => (
<tr key={headerGroup.id}>
{headerGroup.headers.map((header) => (
<th key={header.id}>
<table.FlexRender header={header} />
</th>
))}
</tr>
))}
</thead>
<tbody>
{table.getRowModel().rows.map((row) => (
<tr key={row.id}>
{row.getVisibleCells().map((cell) => (
<td key={cell.id}>
<table.FlexRender cell={cell} />
</td>
))}
</tr>
))}
</tbody>
</table>
<pre id="state">{JSON.stringify(columnVisibility)}</pre>
</>
);
}
チェックボックスの一覧には、隠した列も並べる必要があるので、table.getAllLeafColumns() を使います。使った関数は次のとおりです。
| 関数 | 使い方 |
|---|---|
column.getIsVisible() |
その列が表示されているか。チェックボックスの checked に渡す |
column.getCanHide() |
その列を隠せるか。false の列はチェックボックスを disabled にする |
column.getToggleVisibilityHandler() |
チェックボックスの onChange に渡す関数を返す。チェックの有無が、そのまま表示・非表示になる |
table.getIsAllColumnsVisible() |
すべての列が表示されているか |
table.getToggleAllColumnsVisibilityHandler() |
「すべて」のチェックボックスの onChange に渡す関数を返す |
<pre id="state"> は、検証で columnVisibility の中身を見るためだけに置いたものです。
チェックを外すと、その列の ID に false が入る
最初の表示では、useState に渡した {"memo":false} のとおり、「ひとこと」の列が隠れていました。そこから「体重(kg)」のチェックを外し、もう一度チェックを入れました。
最初の表示
columnVisibility: {"memo":false}
見出し(4個): 名前 | 年齢 | 体重(kg) | 毛の色
1行目(4個): たま | 3 | 4.2 | 茶トラ
----「体重(kg)」のチェックを外した
columnVisibility: {"memo":false,"weight":false}
見出し(3個): 名前 | 年齢 | 毛の色
1行目(3個): たま | 3 | 茶トラ
----「体重(kg)」に、もう一度チェックを入れた
columnVisibility: {"memo":false,"weight":true}
見出し(4個): 名前 | 年齢 | 体重(kg) | 毛の色
チェックを外すと "weight":false が入り、見出しとセルの両方から体重が消えました。チェックを戻すと、weight のキーは消えずに true になりました。ガイドによると、列が隠れるのは、その列の ID が入っていて値が false のときだけです。ID が入っていない列は表示されます。そのため、最初の状態では隠したい列だけを false にしておけば足ります。
チェックボックスにフォーカスしてスペースキーを押したときも、クリックと同じように切り替わりました。

右上のクリックの回数、カーソルの絵とピンクの輪は、撮影用のスクリプトが書き足した表示です。表の列が変わった瞬間に表をピンクの枠で囲み、下の columnVisibility の欄もピンクの背景にしました。右上の回数も、クリックした瞬間だけピンクになります。
「すべて」のチェックボックスは、隠せない列を残す
「すべて」のチェックボックスを2回クリックしたときの記録です。1回目の前は「ひとこと」が隠れていて、「すべて」は後で説明する途中の表示になっていました。
----「すべて」をクリックした
columnVisibility: {"name":true,"age":true,"weight":true,"color":true,"memo":true}
見出し(5個): 名前 | 年齢 | 体重(kg) | 毛の色 | ひとこと
----「すべて」をもう一度クリックした
columnVisibility: {"name":true,"age":false,"weight":false,"color":false,"memo":false}
見出し(1個): 名前
1回目ですべての列が表示され、2回目では enableHiding: false を付けた「名前」だけが残りました。どちらのときも、すべての列の ID に値が入ります。インストールしたパッケージのコードでも、すべての列について、隠すときは隠せない列だけを true、それ以外を false にした新しい状態を作っていました。「名前」のチェックボックスは disabled になっていて、押せない状態のまま無理にクリックしても、状態は変わりませんでした。
「すべて」のチェックボックスには、一部の列だけが表示されているときに、チェックとも空とも違う途中の表示(indeterminate)を出しています。MDN のチェックボックスの説明にあるとおり、indeterminate は HTML の属性では指定できず、JavaScript から indeterminate プロパティに値を設定します。そこで、ref で受け取った input 要素に入れました。
途中の状態は、table.getIsSomeColumnsVisible() では判断していません。この関数は、表示されている列が1つでもあれば true を返します。検証では、「すべて」で名前の列だけにしたあとも true のままでした。隠せない「名前」の列が表示されているためです。そこで、getCanHide() が true の列だけを見て、1つでも表示されているかを調べました。こうすると、名前の列だけのときは空のチェックボックスになり、そこから「年齢」にチェックを入れると途中の表示になりました。
行のセルは getVisibleCells() で出す
表の本体で row.getVisibleCells() の代わりに row.getAllCells() を使うと、隠した列のセルも出てしまいます。セルを出す関数だけを書き換えて、「体重(kg)」のチェックを外しました。
----「体重(kg)」のチェックを外した
columnVisibility: {"memo":false,"weight":false}
見出し(3個): 名前 | 年齢 | 毛の色
1行目(5個): たま | 3 | 4.2 | 茶トラ | 窓辺が好き

見出しは3つに減りましたが、セルは隠した「ひとこと」も含めて5つのままです。「毛の色」の見出しの下に体重の数字が並び、列がずれました。ガイドにも、getAllCells() や getAllLeafColumns() は表示・非表示を考えず、表を描くときは getVisibleCells() や getVisibleLeafColumns() を使うように書かれています。見出しの getHeaderGroups() は、もともと表示・非表示を反映しています。
チェックボックスの一覧は getAllLeafColumns() で全部の列から作り、表の見出しとセルは getHeaderGroups() と getVisibleCells() で表示中の列だけから作ります。この記事の表では、この使い分けでチェックボックスと表の列が一致しました。





