Next.js avec TanStack Table - Tableaux de données avancés

Le panneau des gardiens de la Métropole Quantum affiche des milliers d'enregistrements : utilisateurs, rôles, statuts. Un simple élément table avec une boucle map suffit une semaine, puis quelqu'un demande le tri, une barre de recherche, la pagination et la sélection de plusieurs lignes à la fois. Écrire tout cela à la main, ce sont des centaines de lignes de logique fragile. Matrix, l'architecte des données de la Métropole, règle le problème avec TanStack Table - une bibliothèque qui calcule la logique du tableau et te laisse l'apparence.

Qu'est-ce que TanStack Table ?

TanStack Table (anciennement React Table) est une bibliothèque headless pour construire des tableaux, qui offre :

• Headless UI - un contrôle total sur l'apparence
• TypeScript-first - un support complet du typage
• Framework agnostic - fonctionne avec React, Vue, Svelte
• Feature-rich - tri, filtrage, pagination, grouping
• Performance - des optimisations pour les grands jeux de données
• Extensible - un riche système de plugins

"Headless" signifie que la bibliothèque ne rend aucun HTML. Tu obtiens une API avec un état et des méthodes, et tu écris toi-même le balisage et les styles.

Avantages de TanStack Table

• Aucune dépendance UI - pas de composants ni de styles prêts à l'emploi
• Tree-shakable - seulement les fonctions nécessaires dans le bundle
• Server-side support - idéal pour le SSR/SSG
• Accessibility - l'accessibilité dépend de ton HTML, puisque c'est toi qui l'écris
• Mobile-friendly - des tableaux responsives

Ce que TanStack Table ne fait PAS : il ne récupère pas les données et n'a pas de virtualisation intégrée. Tu fournis les données toi-même (par exemple avec TanStack Query), et la virtualisation des longues listes vient de la bibliothèque séparée TanStack Virtual.

Installation et configuration de base

Installation

Dans un projet React, tu installes l'adaptateur @tanstack/react-table, qui contient déjà le cœur de la bibliothèque :

1# Installe TanStack Table
2npm install @tanstack/react-table
3
4# Cœur indépendant du framework (react-table l'installe automatiquement)
5npm install @tanstack/table-core

Le paquet @tanstack/table-core est le cœur indépendant du framework. L'adaptateur React l'installe automatiquement, donc une installation séparée est optionnelle.

Tableau de base

Chaque tableau commence par un type de données. L'interface User décrit une ligne, et les unions de littéraux, comme 'admin' | 'user' | 'moderator', limitent les valeurs autorisées :

1// types/User.ts
2export interface User {
3  id: string;
4  name: string;
5  email: string;
6  role: 'admin' | 'user' | 'moderator';
7  status: 'active' | 'inactive' | 'pending';
8  createdAt: string;
9  lastLogin?: string;
10}

Grâce à cela, TypeScript suggérera les noms de colonnes et détectera les fautes de frappe dans les clés.

On définit maintenant les colonnes. La fonction createColumnHelper<User>() crée un assistant dont la méthode accessor désigne un champ de l'objet, tandis que cell décide comment afficher la valeur :

1// components/UsersTable.tsx
2'use client';
3
4import {
5  createColumnHelper,
6  flexRender,
7  getCoreRowModel,
8  useReactTable,
9} from '@tanstack/react-table';
10import { User } from '@/types/User';
11
12const columnHelper = createColumnHelper<User>();
13
14const columns = [
15  columnHelper.accessor('name', {
16    header: "Nom d'utilisateur",
17    cell: (info) => info.getValue(),
18  }),
19  columnHelper.accessor('email', {
20    header: 'Email',
21    cell: (info) => (
22      <a href={`mailto:${info.getValue()}`} className="text-blue-600 hover:underline">
23        {info.getValue()}
24      </a>
25    ),
26  }),
27  columnHelper.accessor('role', {
28    header: 'Rôle',
29    cell: (info) => {
30      const role = info.getValue();
31      const roleColors = {
32        admin: 'bg-red-100 text-red-800',
33        moderator: 'bg-yellow-100 text-yellow-800',
34        user: 'bg-green-100 text-green-800',
35      };
36
37      return (
38        <span className={`px-2 py-1 rounded-full text-xs font-medium ${roleColors[role]}`}>
39          {role}
40        </span>
41      );
42    },
43  }),
44  columnHelper.accessor('status', {
45    header: 'Status',
46    cell: (info) => {
47      const status = info.getValue();
48      const statusColors = {
49        active: 'bg-green-100 text-green-800',
50        inactive: 'bg-gray-100 text-gray-800',
51        pending: 'bg-yellow-100 text-yellow-800',
52      };
53
54      return (
55        <span className={`px-2 py-1 rounded-full text-xs font-medium ${statusColors[status]}`}>
56          {status}
57        </span>
58      );
59    },
60  }),
61  columnHelper.accessor('createdAt', {
62    header: 'Date de création',
63    cell: (info) => new Date(info.getValue()).toLocaleDateString('fr-FR'),
64  }),
65];
66

Les colonnes ne sont qu'un tableau de configuration, sans aucun tableau affiché pour l'instant. Le rôle et le statut reçoivent des badges colorés, et la date est formatée selon la locale française.

Le composant relie les données et les colonnes avec le hook useReactTable. La configuration minimale comprend data, columns et getCoreRowModel, le modèle de lignes de base :

1interface UsersTableProps {
2  data: User[];
3}
4
5export default function UsersTable({ data }: UsersTableProps) {
6  const table = useReactTable({
7    data,
8    columns,
9    getCoreRowModel: getCoreRowModel(),
10  });
11
12  return (
13    <div className="overflow-x-auto">
14      <table className="min-w-full bg-white border border-gray-200">
15        <thead className="bg-gray-50">
16          {table.getHeaderGroups().map((headerGroup) => (
17            <tr key={headerGroup.id}>
18              {headerGroup.headers.map((header) => (
19                <th
20                  key={header.id}
21                  className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
22                >
23                  {header.isPlaceholder
24                    ? null
25                    : flexRender(header.column.columnDef.header, header.getContext())}
26                </th>
27              ))}
28            </tr>
29          ))}
30        </thead>
31        <tbody className="bg-white divide-y divide-gray-200">
32          {table.getRowModel().rows.map((row) => (
33            <tr key={row.id} className="hover:bg-gray-50">
34              {row.getVisibleCells().map((cell) => (
35                <td key={cell.id} className="px-6 py-4 whitespace-nowrap text-sm text-gray-900">
36                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
37                </td>
38              ))}
39            </tr>
40          ))}
41        </tbody>
42      </table>
43    </div>
44  );
45}

flexRender affiche un en-tête ou une cellule, que la définition contienne du texte ou une fonction. Tout le HTML et les classes Tailwind sont à nous : la bibliothèque n'a fourni que les groupes d'en-têtes et les lignes.

Tri et filtrage

Tri

Chaque fonctionnalité du tableau suit le même schéma : un état dans useState, son branchement via state et on...Change, et l'ajout du modèle de lignes correspondant. Pour le tri, ce sont SortingState et getSortedRowModel :

1// components/SortableUsersTable.tsx
2'use client';
3
4import {
5  createColumnHelper,
6  flexRender,
7  getCoreRowModel,
8  getSortedRowModel,
9  SortingState,
10  useReactTable,
11} from '@tanstack/react-table';
12import { useState } from 'react';
13import { ChevronUpIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
14import { User } from '@/types/User';
15
16const columnHelper = createColumnHelper<User>();
17
18const columns = [
19  columnHelper.accessor('name', {
20    header: "Nom d'utilisateur",
21    enableSorting: true,
22  }),
23  columnHelper.accessor('email', {
24    header: 'Email',
25    enableSorting: true,
26  }),
27  columnHelper.accessor('role', {
28    header: 'Rôle',
29    enableSorting: true,
30  }),
31  columnHelper.accessor('status', {
32    header: 'Status',
33    enableSorting: true,
34  }),
35  columnHelper.accessor('createdAt', {
36    header: 'Date de création',
37    enableSorting: true,
38    sortingFn: 'datetime',
39    cell: (info) => new Date(info.getValue()).toLocaleDateString('fr-FR'),
40  }),
41];
42
43interface SortableUsersTableProps {
44  data: User[];
45}
46
47export default function SortableUsersTable({ data }: SortableUsersTableProps) {
48  const [sorting, setSorting] = useState<SortingState>([]);
49
50  const table = useReactTable({
51    data,
52    columns,
53    state: {
54      sorting,
55    },
56    onSortingChange: setSorting,
57    getCoreRowModel: getCoreRowModel(),
58    getSortedRowModel: getSortedRowModel(),
59  });
60
61  return (
62    <div className="overflow-x-auto">
63      <table className="min-w-full bg-white border border-gray-200">
64        <thead className="bg-gray-50">
65          {table.getHeaderGroups().map((headerGroup) => (
66            <tr key={headerGroup.id}>
67              {headerGroup.headers.map((header) => (
68                <th
69                  key={header.id}
70                  className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
71                >
72                  <div
73                    className={
74                      header.column.getCanSort()
75                        ? 'flex items-center cursor-pointer select-none hover:text-gray-700'
76                        : ''
77                    }
78                    onClick={header.column.getToggleSortingHandler()}
79                  >
80                    {flexRender(header.column.columnDef.header, header.getContext())}
81                    {header.column.getCanSort() && (
82                      <span className="ml-1">
83                        {header.column.getIsSorted() === 'asc' ? (
84                          <ChevronUpIcon className="w-4 h-4" />
85                        ) : header.column.getIsSorted() === 'desc' ? (
86                          <ChevronDownIcon className="w-4 h-4" />
87                        ) : (
88                          <div className="w-4 h-4" />
89                        )}
90                      </span>
91                    )}
92                  </div>
93                </th>
94              ))}
95            </tr>
96          ))}
97        </thead>
98        <tbody className="bg-white divide-y divide-gray-200">
99          {table.getRowModel().rows.map((row) => (
100            <tr key={row.id} className="hover:bg-gray-50">
101              {row.getVisibleCells().map((cell) => (
102                <td key={cell.id} className="px-6 py-4 whitespace-nowrap text-sm text-gray-900">
103                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
104                </td>
105              ))}
106            </tr>
107          ))}
108        </tbody>
109      </table>
110    </div>
111  );
112}

Un clic sur un en-tête appelle getToggleSortingHandler(), qui fait défiler l'ordre : croissant, décroissant, sans tri. sortingFn: 'datetime' trie les dates chronologiquement et non alphabétiquement.

Filtrage

Le filtrage ajoute deux types d'état : les filtres de colonnes (ColumnFiltersState) et un filtre global pour la barre de recherche. D'abord la configuration avec une fonction globalFilterFn personnalisée :

1// components/FilterableUsersTable.tsx
2'use client';
3
4import {
5  createColumnHelper,
6  flexRender,
7  getCoreRowModel,
8  getFilteredRowModel,
9  getSortedRowModel,
10  SortingState,
11  ColumnFiltersState,
12  useReactTable,
13  GlobalFilterTableState,
14} from '@tanstack/react-table';
15import { useState } from 'react';
16import { MagnifyingGlassIcon } from '@heroicons/react/24/outline';
17import { User } from '@/types/User';
18
19// Fonction de filtre global
20function globalFilterFn(row: any, columnId: string, value: string) {
21  const search = value.toLowerCase();
22  return (
23    row.getValue('name')?.toLowerCase().includes(search) ||
24    row.getValue('email')?.toLowerCase().includes(search) ||
25    row.getValue('role')?.toLowerCase().includes(search)
26  );
27}
28
29const columnHelper = createColumnHelper<User>();
30
31const columns = [
32  columnHelper.accessor('name', {
33    header: "Nom d'utilisateur",
34    enableColumnFilter: true,
35    filterFn: 'includesString',
36  }),
37  columnHelper.accessor('email', {
38    header: 'Email',
39    enableColumnFilter: true,
40  }),
41  columnHelper.accessor('role', {
42    header: 'Rôle',
43    enableColumnFilter: true,
44    filterFn: 'equals',
45  }),
46  columnHelper.accessor('status', {
47    header: 'Status',
48    enableColumnFilter: true,
49    filterFn: 'equals',
50  }),
51  columnHelper.accessor('createdAt', {
52    header: 'Date de création',
53    enableColumnFilter: false,
54    cell: (info) => new Date(info.getValue()).toLocaleDateString('fr-FR'),
55  }),
56];
57
58interface FilterableUsersTableProps {
59  data: User[];
60}
61
62export default function FilterableUsersTable({ data }: FilterableUsersTableProps) {
63  const [sorting, setSorting] = useState<SortingState>([]);
64  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
65  const [globalFilter, setGlobalFilter] = useState('');
66
67  const table = useReactTable({
68    data,
69    columns,
70    state: {
71      sorting,
72      columnFilters,
73      globalFilter,
74    },
75    onSortingChange: setSorting,
76    onColumnFiltersChange: setColumnFilters,
77    onGlobalFilterChange: setGlobalFilter,
78    globalFilterFn,
79    getCoreRowModel: getCoreRowModel(),
80    getSortedRowModel: getSortedRowModel(),
81    getFilteredRowModel: getFilteredRowModel(),
82  });
83

Tu choisis les fonctions de filtre intégrées, comme includesString ou equals, par leur nom. Le modèle getFilteredRowModel écarte les lignes qui ne correspondent pas aux filtres, et le tri continue de s'appliquer à ce qui reste.

L'interface des filtres se compose de simples champs de formulaire qui définissent les valeurs via l'API du tableau :

1  return (
2    <div className="space-y-4">
3      {/* Global Search */}
4      <div className="flex items-center space-x-4">
5        <div className="relative flex-1 max-w-sm">
6          <MagnifyingGlassIcon className="absolute left-3 top-1/2 transform -translate-y-1/2 w-4 h-4 text-gray-400" />
7          <input
8            value={globalFilter ?? ''}
9            onChange={(e) => setGlobalFilter(e.target.value)}
10            className="pl-10 pr-4 py-2 border border-gray-300 rounded-md focus:ring-blue-500 focus:border-blue-500 w-full"
11          />
12        </div>
13
14        {/* Roles Filter */}
15        <select
16          value={(table.getColumn('role')?.getFilterValue() as string) ?? ''}
17          onChange={(e) =>
18            table.getColumn('role')?.setFilterValue(e.target.value || undefined)
19          }
20          className="px-3 py-2 border border-gray-300 rounded-md focus:ring-blue-500 focus:border-blue-500"
21        >
22          <option value="">Tous les rôles</option>
23          <option value="admin">Admin</option>
24          <option value="moderator">Moderator</option>
25          <option value="user">User</option>
26        </select>
27
28        {/* Status Filter */}
29        <select
30          value={(table.getColumn('status')?.getFilterValue() as string) ?? ''}
31          onChange={(e) =>
32            table.getColumn('status')?.setFilterValue(e.target.value || undefined)
33          }
34          className="px-3 py-2 border border-gray-300 rounded-md focus:ring-blue-500 focus:border-blue-500"
35        >
36          <option value="">Tous les statuts</option>
37          <option value="active">Actif</option>
38          <option value="inactive">Inactif</option>
39          <option value="pending">En attente</option>
40        </select>
41      </div>
42
43      {/* Results Info */}
44      <div className="text-sm text-gray-600">
45        Affichage de {table.getFilteredRowModel().rows.length} sur {data.length} utilisateurs
46      </div>
47
48      {/* Table */}
49      <div className="overflow-x-auto">
50        <table className="min-w-full bg-white border border-gray-200">
51          <thead className="bg-gray-50">
52            {table.getHeaderGroups().map((headerGroup) => (
53              <tr key={headerGroup.id}>
54                {headerGroup.headers.map((header) => (
55                  <th
56                    key={header.id}
57                    className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
58                  >
59                    <div
60                      className={
61                        header.column.getCanSort()
62                          ? 'flex items-center cursor-pointer select-none hover:text-gray-700'
63                          : ''
64                      }
65                      onClick={header.column.getToggleSortingHandler()}
66                    >
67                      {flexRender(header.column.columnDef.header, header.getContext())}
68                    </div>
69                  </th>
70                ))}
71              </tr>
72            ))}
73          </thead>
74          <tbody className="bg-white divide-y divide-gray-200">
75            {table.getRowModel().rows.map((row) => (
76              <tr key={row.id} className="hover:bg-gray-50">
77                {row.getVisibleCells().map((cell) => (
78                  <td key={cell.id} className="px-6 py-4 whitespace-nowrap text-sm text-gray-900">
79                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
80                  </td>
81                ))}
82              </tr>
83            ))}
84          </tbody>
85        </table>
86      </div>
87    </div>
88  );
89}

Dans tbody, on utilise getRowModel(), car il renvoie le résultat final après filtrage et tri. getFilteredRowModel() ignorerait le tri, donc ici il ne sert qu'au compteur de résultats.

Pagination

La pagination garde dans l'état le numéro de page (pageIndex, compté à partir de zéro) et la taille de page (pageSize). Le modèle getPaginationRowModel découpe les lignes en pages :

1// components/PaginatedUsersTable.tsx
2'use client';
3
4import {
5  createColumnHelper,
6  flexRender,
7  getCoreRowModel,
8  getPaginationRowModel,
9  getSortedRowModel,
10  getFilteredRowModel,
11  PaginationState,
12  useReactTable,
13} from '@tanstack/react-table';
14import { useState } from 'react';
15import {
16  ChevronLeftIcon,
17  ChevronRightIcon,
18  ChevronDoubleLeftIcon,
19  ChevronDoubleRightIcon
20} from '@heroicons/react/24/outline';
21import { User } from '@/types/User';
22
23const columnHelper = createColumnHelper<User>();
24
25const columns = [
26  columnHelper.accessor('name', {
27    header: "Nom d'utilisateur",
28  }),
29  columnHelper.accessor('email', {
30    header: 'Email',
31  }),
32  columnHelper.accessor('role', {
33    header: 'Rôle',
34    cell: (info) => {
35      const role = info.getValue();
36      return (
37        <span className="px-2 py-1 rounded-full text-xs font-medium bg-blue-100 text-blue-800">
38          {role}
39        </span>
40      );
41    },
42  }),
43  columnHelper.accessor('status', {
44    header: 'Status',
45    cell: (info) => {
46      const status = info.getValue();
47      const colors = {
48        active: 'bg-green-100 text-green-800',
49        inactive: 'bg-gray-100 text-gray-800',
50        pending: 'bg-yellow-100 text-yellow-800',
51      };
52
53      return (
54        <span className={`px-2 py-1 rounded-full text-xs font-medium ${colors[status]}`}>
55          {status}
56        </span>
57      );
58    },
59  }),
60  columnHelper.accessor('createdAt', {
61    header: 'Date de création',
62    cell: (info) => new Date(info.getValue()).toLocaleDateString('fr-FR'),
63  }),
64];
65
66interface PaginatedUsersTableProps {
67  data: User[];
68}
69
70export default function PaginatedUsersTable({ data }: PaginatedUsersTableProps) {
71  const [pagination, setPagination] = useState<PaginationState>({
72    pageIndex: 0,
73    pageSize: 10,
74  });
75
76  const table = useReactTable({
77    data,
78    columns,
79    state: {
80      pagination,
81    },
82    onPaginationChange: setPagination,
83    getCoreRowModel: getCoreRowModel(),
84    getSortedRowModel: getSortedRowModel(),
85    getFilteredRowModel: getFilteredRowModel(),
86    getPaginationRowModel: getPaginationRowModel(),
87  });
88

Le tableau calcule lui-même le nombre de pages à partir du nombre de lignes et de pageSize. Tu n'as pas besoin de garder une tranche des données dans une variable séparée.

Les contrôles de navigation utilisent des méthodes prêtes à l'emploi comme previousPage(), nextPage() et setPageIndex() :

1  return (
2    <div className="space-y-4">
3      {/* Table */}
4      <div className="overflow-x-auto">
5        <table className="min-w-full bg-white border border-gray-200">
6          <thead className="bg-gray-50">
7            {table.getHeaderGroups().map((headerGroup) => (
8              <tr key={headerGroup.id}>
9                {headerGroup.headers.map((header) => (
10                  <th
11                    key={header.id}
12                    className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
13                  >
14                    {flexRender(header.column.columnDef.header, header.getContext())}
15                  </th>
16                ))}
17              </tr>
18            ))}
19          </thead>
20          <tbody className="bg-white divide-y divide-gray-200">
21            {table.getRowModel().rows.map((row) => (
22              <tr key={row.id} className="hover:bg-gray-50">
23                {row.getVisibleCells().map((cell) => (
24                  <td key={cell.id} className="px-6 py-4 whitespace-nowrap text-sm text-gray-900">
25                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
26                  </td>
27                ))}
28              </tr>
29            ))}
30          </tbody>
31        </table>
32      </div>
33
34      {/* Pagination */}
35      <div className="flex items-center justify-between">
36        <div className="flex items-center space-x-2">
37          <span className="text-sm text-gray-700">
38            Showing{' '}
39            <span className="font-medium">
40              {table.getState().pagination.pageIndex * table.getState().pagination.pageSize + 1}
41            </span>{' '}
42            -{' '}
43            <span className="font-medium">
44              {Math.min(
45                (table.getState().pagination.pageIndex + 1) * table.getState().pagination.pageSize,
46                table.getFilteredRowModel().rows.length
47              )}
48            </span>{' '}
49            of{' '}
50            <span className="font-medium">{table.getFilteredRowModel().rows.length}</span> results
51          </span>
52
53          <select
54            value={table.getState().pagination.pageSize}
55            onChange={(e) => {
56              table.setPageSize(Number(e.target.value));
57            }}
58            className="px-3 py-1 border border-gray-300 rounded text-sm"
59          >
60            {[10, 20, 30, 40, 50].map((pageSize) => (
61              <option key={pageSize} value={pageSize}>
62                {pageSize} par page
63              </option>
64            ))}
65          </select>
66        </div>
67
68        <div className="flex items-center space-x-2">
69          <button
70            onClick={() => table.setPageIndex(0)}
71            disabled={!table.getCanPreviousPage()}
72            className="p-2 border border-gray-300 rounded disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50"
73          >
74            <ChevronDoubleLeftIcon className="w-4 h-4" />
75          </button>
76
77          <button
78            onClick={() => table.previousPage()}
79            disabled={!table.getCanPreviousPage()}
80            className="p-2 border border-gray-300 rounded disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50"
81          >
82            <ChevronLeftIcon className="w-4 h-4" />
83          </button>
84
85          <div className="flex items-center space-x-1">
86            <span className="text-sm text-gray-700">Page</span>
87            <input
88              type="number"
89              value={table.getState().pagination.pageIndex + 1}
90              onChange={(e) => {
91                const page = e.target.value ? Number(e.target.value) - 1 : 0;
92                table.setPageIndex(page);
93              }}
94              className="w-16 px-2 py-1 border border-gray-300 rounded text-sm text-center"
95              min={1}
96              max={table.getPageCount()}
97            />
98            <span className="text-sm text-gray-700">sur {table.getPageCount()}</span>
99          </div>
100
101          <button
102            onClick={() => table.nextPage()}
103            disabled={!table.getCanNextPage()}
104            className="p-2 border border-gray-300 rounded disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50"
105          >
106            <ChevronRightIcon className="w-4 h-4" />
107          </button>
108
109          <button
110            onClick={() => table.setPageIndex(table.getPageCount() - 1)}
111            disabled={!table.getCanNextPage()}
112            className="p-2 border border-gray-300 rounded disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50"
113          >
114            <ChevronDoubleRightIcon className="w-4 h-4" />
115          </button>
116        </div>
117      </div>
118    </div>
119  );
120}

getCanPreviousPage() et getCanNextPage() désactivent les boutons aux extrémités. Le champ du numéro de page soustrait 1, car l'utilisateur compte à partir de un et le tableau à partir de zéro.

Sélection de lignes

La sélection ajoute une colonne de cases à cocher. La méthode columnHelper.display crée une colonne sans champ de données, parfaite pour les cases à cocher et les boutons d'action :

1// components/SelectableUsersTable.tsx
2'use client';
3
4import {
5  createColumnHelper,
6  flexRender,
7  getCoreRowModel,
8  useReactTable,
9  RowSelectionState,
10} from '@tanstack/react-table';
11import { useState } from 'react';
12import { TrashIcon, UserGroupIcon } from '@heroicons/react/24/outline';
13import { User } from '@/types/User';
14
15const columnHelper = createColumnHelper<User>();
16
17interface SelectableUsersTableProps {
18  data: User[];
19  onDeleteSelected?: (selectedUsers: User[]) => void;
20  onBulkAction?: (action: string, selectedUsers: User[]) => void;
21}
22
23export default function SelectableUsersTable({
24  data,
25  onDeleteSelected,
26  onBulkAction
27}: SelectableUsersTableProps) {
28  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
29
30  const columns = [
31    // Colonne de sélection
32    columnHelper.display({
33      id: 'select',
34      header: ({ table }) => (
35        <input
36          type="checkbox"
37          checked={table.getIsAllRowsSelected()}
38          onChange={table.getToggleAllRowsSelectedHandler()}
39          className="rounded border-gray-300 text-blue-600 focus:ring-blue-500"
40        />
41      ),
42      cell: ({ row }) => (
43        <input
44          type="checkbox"
45          checked={row.getIsSelected()}
46          onChange={row.getToggleSelectedHandler()}
47          className="rounded border-gray-300 text-blue-600 focus:ring-blue-500"
48        />
49      ),
50    }),
51    columnHelper.accessor('name', {
52      header: "Nom d'utilisateur",
53    }),
54    columnHelper.accessor('email', {
55      header: 'Email',
56    }),
57    columnHelper.accessor('role', {
58      header: 'Rôle',
59    }),
60    columnHelper.accessor('status', {
61      header: 'Status',
62    }),
63    // Colonne d'actions
64    columnHelper.display({
65      id: 'actions',
66      header: 'Actions',
67      cell: ({ row }) => (
68        <div className="flex space-x-2">
69          <button
70            onClick={() => console.log('Edit user:', row.original)}
71            className="text-blue-600 hover:text-blue-800 text-sm"
72          >
73            Modifier
74          </button>
75          <button
76            onClick={() => console.log('Delete user:', row.original)}
77            className="text-red-600 hover:text-red-800 text-sm"
78          >
79            Supprimer
80          </button>
81        </div>
82      ),
83    }),
84  ];
85
86  const table = useReactTable({
87    data,
88    columns,
89    state: {
90      rowSelection,
91    },
92    onRowSelectionChange: setRowSelection,
93    getCoreRowModel: getCoreRowModel(),
94    enableRowSelection: true,
95  });
96
97  const selectedUsers = table.getFilteredSelectedRowModel().rows.map(row => row.original);
98

L'état RowSelectionState est un objet dont les clés sont les id des lignes. Les colonnes sont ici définies dans le composant, il vaut donc la peine de les envelopper dans useMemo, comme l'expliquent les bonnes pratiques à la fin de la leçon.

La barre d'actions groupées n'apparaît que lorsque quelque chose est sélectionné :

1  return (
2    <div className="space-y-4">
3      {/* Bulk Actions */}
4      {Object.keys(rowSelection).length > 0 && (
5        <div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
6          <div className="flex items-center justify-between">
7            <div className="flex items-center space-x-2">
8              <UserGroupIcon className="w-5 h-5 text-blue-600" />
9              <span className="text-sm font-medium text-blue-900">
10                {selectedUsers.length} utilisateurs sélectionnés
11              </span>
12            </div>
13
14            <div className="flex space-x-2">
15              <button
16                onClick={() => onBulkAction?.('activate', selectedUsers)}
17                className="px-3 py-1 bg-green-600 text-white text-sm rounded hover:bg-green-700"
18              >
19                Activer
20              </button>
21              <button
22                onClick={() => onBulkAction?.('deactivate', selectedUsers)}
23                className="px-3 py-1 bg-yellow-600 text-white text-sm rounded hover:bg-yellow-700"
24              >
25                Désactiver
26              </button>
27              <button
28                onClick={() => onDeleteSelected?.(selectedUsers)}
29                className="px-3 py-1 bg-red-600 text-white text-sm rounded hover:bg-red-700 flex items-center space-x-1"
30              >
31                <TrashIcon className="w-4 h-4" />
32                <span>Supprimer</span>
33              </button>
34            </div>
35          </div>
36        </div>
37      )}
38
39      {/* Table */}
40      <div className="overflow-x-auto">
41        <table className="min-w-full bg-white border border-gray-200">
42          <thead className="bg-gray-50">
43            {table.getHeaderGroups().map((headerGroup) => (
44              <tr key={headerGroup.id}>
45                {headerGroup.headers.map((header) => (
46                  <th
47                    key={header.id}
48                    className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
49                  >
50                    {flexRender(header.column.columnDef.header, header.getContext())}
51                  </th>
52                ))}
53              </tr>
54            ))}
55          </thead>
56          <tbody className="bg-white divide-y divide-gray-200">
57            {table.getRowModel().rows.map((row) => (
58              <tr
59                key={row.id}
60                className={`hover:bg-gray-50 ${row.getIsSelected() ? 'bg-blue-50' : ''}`}
61              >
62                {row.getVisibleCells().map((cell) => (
63                  <td key={cell.id} className="px-6 py-4 whitespace-nowrap text-sm text-gray-900">
64                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
65                  </td>
66                ))}
67              </tr>
68            ))}
69          </tbody>
70        </table>
71      </div>
72    </div>
73  );
74}

getFilteredSelectedRowModel() renvoie les lignes sélectionnées, et row.original est l'objet User d'origine. Le tableau ne supprime pas les données lui-même, il les transmet aux fonctions reçues en props.

Récupération des données côté serveur

Avec des dizaines de milliers d'enregistrements, on déplace le tri et le filtrage sur le serveur. L'ordre est fixe : un endpoint d'API, un état manuel de tri et de filtres dans le tableau, le traitement sur le serveur et la gestion de la réponse dans le composant. TanStack Query récupère les données :

1// hooks/useUsersData.ts
2import { useQuery, keepPreviousData } from '@tanstack/react-query';
3import { useState } from 'react';
4
5interface UseUsersDataParams {
6  page: number;
7  pageSize: number;
8  sorting?: Array<{ id: string; desc: boolean }>;
9  filters?: Array<{ id: string; value: any }>;
10  globalFilter?: string;
11}
12
13interface UsersResponse {
14  data: User[];
15  totalCount: number;
16  pageCount: number;
17}
18
19export function useUsersData(params: UseUsersDataParams) {
20  return useQuery({
21    queryKey: ['users', params],
22    queryFn: async (): Promise<UsersResponse> => {
23      const searchParams = new URLSearchParams({
24        page: params.page.toString(),
25        pageSize: params.pageSize.toString(),
26        ...(params.globalFilter && { search: params.globalFilter }),
27        ...(params.sorting?.length && {
28          sort: JSON.stringify(params.sorting)
29        }),
30        ...(params.filters?.length && {
31          filters: JSON.stringify(params.filters)
32        }),
33      });
34
35      const response = await fetch(`/api/users?${searchParams}`);
36
37      if (!response.ok) {
38        throw new Error('Failed to fetch users');
39      }
40
41      return response.json();
42    },
43    placeholderData: keepPreviousData,
44  });
45}

queryKey contient les paramètres, donc chaque changement de page ou de tri récupère de nouvelles données. placeholderData: keepPreviousData est l'écriture de TanStack Query 5 qui affiche la page précédente jusqu'à l'arrivée de la nouvelle, l'ancienne option keepPreviousData: true ne fonctionne plus.

Le composant transmet l'état du tableau au hook et active le mode manuel avec les indicateurs manualPagination, manualSorting et manualFiltering :

1// components/ServerSideUsersTable.tsx
2'use client';
3
4import {
5  createColumnHelper,
6  flexRender,
7  getCoreRowModel,
8  useReactTable,
9  PaginationState,
10  SortingState,
11  ColumnFiltersState,
12} from '@tanstack/react-table';
13import { useState } from 'react';
14import { useUsersData } from '@/hooks/useUsersData';
15import { User } from '@/types/User';
16
17const columnHelper = createColumnHelper<User>();
18
19const columns = [
20  columnHelper.accessor('name', {
21    header: "Nom d'utilisateur",
22    enableSorting: true,
23  }),
24  columnHelper.accessor('email', {
25    header: 'Email',
26    enableSorting: true,
27  }),
28  columnHelper.accessor('role', {
29    header: 'Rôle',
30    enableSorting: true,
31  }),
32  columnHelper.accessor('status', {
33    header: 'Status',
34    enableSorting: true,
35  }),
36  columnHelper.accessor('createdAt', {
37    header: 'Date de création',
38    enableSorting: true,
39    cell: (info) => new Date(info.getValue()).toLocaleDateString('fr-FR'),
40  }),
41];
42
43export default function ServerSideUsersTable() {
44  const [pagination, setPagination] = useState<PaginationState>({
45    pageIndex: 0,
46    pageSize: 10,
47  });
48  const [sorting, setSorting] = useState<SortingState>([]);
49  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
50  const [globalFilter, setGlobalFilter] = useState('');
51
52  const { data, isLoading, error } = useUsersData({
53    page: pagination.pageIndex,
54    pageSize: pagination.pageSize,
55    sorting,
56    filters: columnFilters,
57    globalFilter,
58  });
59
60  const table = useReactTable({
61    data: data?.data ?? [],
62    columns,
63    pageCount: data?.pageCount ?? -1,
64    state: {
65      pagination,
66      sorting,
67      columnFilters,
68      globalFilter,
69    },
70    onPaginationChange: setPagination,
71    onSortingChange: setSorting,
72    onColumnFiltersChange: setColumnFilters,
73    onGlobalFilterChange: setGlobalFilter,
74    getCoreRowModel: getCoreRowModel(),
75    manualPagination: true,
76    manualSorting: true,
77    manualFiltering: true,
78  });
79
80  if (isLoading) {
81    return (
82      <div className="flex items-center justify-center h-64">
83        <div className="animate-spin rounded-full h-32 w-32 border-b-2 border-blue-600"></div>
84      </div>
85    );
86  }
87
88  if (error) {
89    return (
90      <div className="text-center text-red-600 p-8">
91        Une erreur est survenue lors du chargement des données
92      </div>
93    );
94  }
95

En mode manuel, le tableau ne trie ni ne filtre lui-même, il signale seulement les changements d'état. pageCount vient du serveur, car seul le serveur connaît le nombre total d'enregistrements.

La vue ressemble presque à la version client :

1  return (
2    <div className="space-y-4">
3      {/* Search */}
4      <div className="flex items-center space-x-4">
5        <input
6          value={globalFilter ?? ''}
7          onChange={(e) => setGlobalFilter(e.target.value)}
8          className="px-3 py-2 border border-gray-300 rounded-md focus:ring-blue-500 focus:border-blue-500 flex-1 max-w-sm"
9        />
10      </div>
11
12      {/* Table */}
13      <div className="overflow-x-auto">
14        <table className="min-w-full bg-white border border-gray-200">
15          <thead className="bg-gray-50">
16            {table.getHeaderGroups().map((headerGroup) => (
17              <tr key={headerGroup.id}>
18                {headerGroup.headers.map((header) => (
19                  <th
20                    key={header.id}
21                    className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
22                  >
23                    <div
24                      className={
25                        header.column.getCanSort()
26                          ? 'flex items-center cursor-pointer select-none hover:text-gray-700'
27                          : ''
28                      }
29                      onClick={header.column.getToggleSortingHandler()}
30                    >
31                      {flexRender(header.column.columnDef.header, header.getContext())}
32                    </div>
33                  </th>
34                ))}
35              </tr>
36            ))}
37          </thead>
38          <tbody className="bg-white divide-y divide-gray-200">
39            {table.getRowModel().rows.map((row) => (
40              <tr key={row.id} className="hover:bg-gray-50">
41                {row.getVisibleCells().map((cell) => (
42                  <td key={cell.id} className="px-6 py-4 whitespace-nowrap text-sm text-gray-900">
43                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
44                  </td>
45                ))}
46              </tr>
47            ))}
48          </tbody>
49        </table>
50      </div>
51
52      {/* Pagination */}
53      <div className="flex items-center justify-between">
54        <div className="text-sm text-gray-700">
55          Affichage de {data?.data.length ?? 0} sur {data?.totalCount ?? 0} utilisateurs
56        </div>
57
58        <div className="flex items-center space-x-2">
59          <button
60            onClick={() => table.setPageIndex(0)}
61            disabled={!table.getCanPreviousPage()}
62            className="px-3 py-1 border border-gray-300 rounded disabled:opacity-50"
63          >
64            Premier
65          </button>
66
67          <button
68            onClick={() => table.previousPage()}
69            disabled={!table.getCanPreviousPage()}
70            className="px-3 py-1 border border-gray-300 rounded disabled:opacity-50"
71          >
72            Précédent
73          </button>
74
75          <span className="text-sm">
76            Page {table.getState().pagination.pageIndex + 1} sur{' '}
77            {table.getPageCount()}
78          </span>
79
80          <button
81            onClick={() => table.nextPage()}
82            disabled={!table.getCanNextPage()}
83            className="px-3 py-1 border border-gray-300 rounded disabled:opacity-50"
84          >
85            Suivant
86          </button>
87
88          <button
89            onClick={() => table.setPageIndex(table.getPageCount() - 1)}
90            disabled={!table.getCanNextPage()}
91            className="px-3 py-1 border border-gray-300 rounded disabled:opacity-50"
92          >
93            Dernier
94          </button>
95        </div>
96      </div>
97    </div>
98  );
99}