ReactとTanStack Tableで、表示する列をチェックボックスで選ぶ方法

​​React​TanStack Table,TypeScript

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 以降で動くとされています。

text
npm install @tanstack/react-table

v9 では、表を useTable で作り、使う機能を tableFeatures() で登録します。列の表示・非表示は columnVisibilityFeature です。列の表示・非表示のガイドに、これを features に加えると関係する API が使えるようになると書かれています。

tableFeatures({}) のように機能を登録しないで作った表で column.getIsVisible() を呼ぶと、型チェックの段階でエラーになりました。

text
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行にしました。

ts
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 をキーにした名前の対応表などを使うようにすすめられています。ここでは対応表を作り、見出しにも同じ名前を使いました。

ts
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 の書き方にしました。

tsx
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)」のチェックを外し、もう一度チェックを入れました。

text
最初の表示
  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 にしておけば足ります。

チェックボックスにフォーカスしてスペースキーを押したときも、クリックと同じように切り替わりました。

チェックボックスを5回クリックする様子。体重と毛の色のチェックを外し、「すべて」で全部の列を出し、もう一度「すべて」で名前の列だけにし、年齢にチェックを入れる。下の欄に columnVisibility の中身が出ている
チェックボックスを5回クリックしたときの、表の列と columnVisibility の変わり方

右上のクリックの回数、カーソルの絵とピンクの輪は、撮影用のスクリプトが書き足した表示です。表の列が変わった瞬間に表をピンクの枠で囲み、下の columnVisibility の欄もピンクの背景にしました。右上の回数も、クリックした瞬間だけピンクになります。

「すべて」のチェックボックスは、隠せない列を残す

「すべて」のチェックボックスを2回クリックしたときの記録です。1回目の前は「ひとこと」が隠れていて、「すべて」は後で説明する途中の表示になっていました。

text
----「すべて」をクリックした
  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)」のチェックを外しました。

text
----「体重(kg)」のチェックを外した
  columnVisibility: {"memo":false,"weight":false}
  見出し(3個): 名前 | 年齢 | 毛の色
  1行目(5個): たま | 3 | 4.2 | 茶トラ | 窓辺が好き
getAllCells() で行を出した表。見出しは名前・年齢・毛の色の3つなのに、各行には体重とひとことを含む5つのセルが並び、毛の色の見出しの下に体重の値が出ている
行のセルを getAllCells() で出すと、見出しとセルの列がずれる

見出しは3つに減りましたが、セルは隠した「ひとこと」も含めて5つのままです。「毛の色」の見出しの下に体重の数字が並び、列がずれました。ガイドにも、getAllCells() や getAllLeafColumns() は表示・非表示を考えず、表を描くときは getVisibleCells() や getVisibleLeafColumns() を使うように書かれています。見出しの getHeaderGroups() は、もともと表示・非表示を反映しています。

ポイント

チェックボックスの一覧は getAllLeafColumns() で全部の列から作り、表の見出しとセルは getHeaderGroups() と getVisibleCells() で表示中の列だけから作ります。この記事の表では、この使い分けでチェックボックスと表の列が一致しました。

​Posted by 86