Как спроектировать компонент таблицы данных (data table)
На этой странице
Data table — частая задача на проектирование переиспользуемого компонента для админок и дашбордов: сортировка, фильтры, пагинация, выбор строк, изменение ширины и порядка колонок, закрепленные колонки, редактирование ячеек и десятки тысяч строк. Ключевые решения: headless-ядро + рендер (как TanStack Table), контролируемое и неконтролируемое состояние, серверный или клиентский режим обработки данных, виртуализация строк и колонок и доступная разметка <table> или ARIA grid.
Вопрос
Как спроектировать переиспользуемый компонент таблицы данных? Как разделить логику и разметку, поддержать серверную сортировку и пагинацию и отображать тысячи строк?
R — требования
- колонки задаются конфигурацией: заголовок, доступ к значению, рендер ячейки;
- сортировка (по одной или нескольким колонкам), фильтры, пагинация;
- выбор строк (чекбоксы), массовые действия;
- изменение ширины, скрытие и порядок колонок, закрепленные колонки;
- нефункциональные: 10 000+ строк без лагов, серверный режим для больших данных, a11y, кастомизация внешнего вида, сохранение настроек пользователя.
A — архитектура
useTable(options) headless-ядро: состояние и вычисления
├─ columns, data
├─ sorting / filters / pagination / selection / columnSizing state
└─ getRowModel(): строки после фильтрации, сортировки и пагинации
<DataTable> разметка по умолчанию (можно заменить)
├─ <Toolbar> поиск, фильтры, видимость колонок, экспорт
├─ <Table>
│ ├─ <Header> сортировка, resize, меню колонки
│ └─ <VirtualBody> виртуализированные строки
└─ <Pagination>D — модель данных и состояние
type ColumnDef<T> = {
id: string;
header: string;
accessor: (row: T) => unknown;
cell?: (value: unknown, row: T) => React.ReactNode;
sortable?: boolean;
width?: number;
pinned?: "left" | "right";
};
type TableState = {
sorting: { id: string; desc: boolean }[];
filters: { id: string; value: unknown }[];
pagination: { pageIndex: number; pageSize: number };
rowSelection: Record<string, boolean>; // по id строки, а не индексу
columnVisibility: Record<string, boolean>;
columnOrder: string[];
columnSizing: Record<string, number>;
};I — API компонента
<DataTable<User>
columns={columns}
data={data?.items ?? []}
getRowId={(row) => row.id}
mode="server" // или "client"
rowCount={data?.total}
state={{ sorting, pagination }} // controlled
onSortingChange={setSorting}
onPaginationChange={setPagination}
onRowSelectionChange={setSelection}
isLoading={isFetching}
emptyState={<p>Пользователей нет</p>}
/>Серверный режим: изменение сортировки или страницы → запрос GET /api/users?sort=name:asc&page=2&pageSize=50 → новые data и rowCount. Состояние таблицы удобно хранить в URL.
O — оптимизации
Клиентский или серверный режим:
| Клиентский | Серверный | |
|---|---|---|
| Объем данных | до ~10 тыс. строк | любой |
| Сортировка и фильтры | мгновенно в памяти | запрос к API |
| Сложность | ниже | нужно синхронизировать состояние и запросы |
Производительность:
- виртуализация строк (и колонок для широких таблиц), фиксированная или измеряемая высота строк;
- мемоизация
columnsиdata, иначе пересчет модели на каждый рендер; - тяжелая сортировка и фильтрация больших массивов — в Web Worker или на сервере;
- при серверном режиме — показывать старые строки с индикатором, пока грузятся новые (без мигания).
Выбор строк: по rowId, а не индексу — выбор сохраняется при сортировке и пагинации; «выбрать все» уточняет: на странице или все результаты на сервере.
Настройки пользователя: видимость, порядок и ширина колонок сохраняются в localStorage или профиле.
Доступность:
- для данных только для чтения — нативная
<table>с<caption>,<th scope="col">; - сортировка — кнопка в заголовке с
aria-sort="ascending|descending"; - для интерактивной таблицы с навигацией стрелками по ячейкам — паттерн ARIA grid (
role="grid", roving tabindex); - при виртуализации —
aria-rowcountиaria-rowindex.
Что важно помнить
- Headless-подход (логика отдельно от разметки) делает компонент переиспользуемым в разных дизайн-системах; готовое решение — TanStack Table.
- Поддерживайте controlled и uncontrolled режимы для каждого куска состояния.
- Не изобретайте свою grid-навигацию без необходимости — нативная таблица доступна из коробки.
- Связанные темы: виртуализация, пагинация.
Мини-шпаргалка
Headless useTable + заменяемая разметка. Колонки — конфигурация. Состояние: sorting, filters, pagination, selection по id, visibility, order, sizing — controlled или нет. Клиентский режим до ~10 тыс. строк, серверный — для больших. Виртуализация, мемоизация, настройки в localStorage. a11y: <table>, aria-sort, grid для интерактива.
Документация
TanStack Table, APG: Table Pattern, APG: Grid Pattern, TanStack Virtual.