Data Table

TanStack Table v9 drawn on shadcn's stock Table. The core renders any table you build with useTable; sorting, filters, pagination, selection, pinning, grouping, editing, drag and drop, virtual rows and URL state are parts you add one at a time. Your data, columns and state stay yours.

What it is

The data table is a plugin: a component of cilo's own, installed as source into your project, so you read it, change it and own it. It follows shadcn's data table guide and its tasks example, and comes as one core and twenty-eight parts. You install the core and only the parts your table needs.

@cilo/data-table
The core: DataTable, DataTableHeader, DataTableBody, DataTableFooter, the head, row and cell parts, the empty row, and the shared types and column meta in data-table-types.
Parts
@cilo/data-table-<part>, each in its own file beside the core, each bringing the core with it.

A data table is for records people compare, sort, filter and act on. A short static table of a few rows, a document's table or a chart's table view is better as the stock Table on its own.

Installation

With cilo's registry in your components.json (see Installation), add the core, then the parts you want:

Terminal
npx shadcn@latest add @cilo/data-table
npx shadcn@latest add @cilo/data-table-column-header @cilo/data-table-toolbar @cilo/data-table-pagination

The CLI writes the files to components/cilo/data-table/, adds the stock shadcn components each part is drawn with (Table, Button, DropdownMenu, Popover and so on) and installs @tanstack/react-table. The virtual body adds @tanstack/react-virtual, the drag and drop parts and the sort menu add @dnd-kit. Import from where the files landed:

components/payments.tsx
import {
DataTable,
DataTableHeader,
DataTableBody,
DataTableFooter,
} from "@/components/cilo/data-table/data-table"
import { dataTableMeta } from "@/components/cilo/data-table/data-table-types"

The plugin is written for TanStack Table v9. In a project that already uses v8 for tables of its own, adding any data table item upgrades the package to v9, and that code has to move to v9's API as well (tableFeatures, useTable with features, createColumnHelper typed by them). Until it has, v9's @tanstack/react-table/legacy entry (useLegacyTable with the get*RowModel() stubs) keeps v8-style code running beside the plugin.

Anatomy

You build the table with TanStack's useTable; DataTable draws it. With no children it draws a header, a body and, when columns have footers, a footer. Give children to compose your own.

StructureTSX
<DataTable table={table} empty={<DataTableNoResults table={table} />}>
<DataTableHeader />
<DataTableBody />
<DataTableFooter />
</DataTable>
DataTable
The root: the stock Table in its rounded frame, reading every feature off the table it is given.
DataTableHeader
The header rows, one per header group, sticky when DataTable's stickyHeader is set.
DataTableBody
The rows, pinned rows in bodies of their own, detail rows under expanded rows, and the empty row when nothing is left. Its id lets an expand button name it in aria-controls when each body holds one parent row.
DataTableFooter
The column footers, drawn only when a column defines one.
DataTableColumnCell
A body cell laid out as its column's cells are (width, alignment, pinned edge), for a row with no record behind it such as a loading placeholder.

Usage

A table with a search box, sortable headers and pages. Each part exports the TanStack features it needs as a fragment you spread into tableFeatures, next to dataTableMeta, which types the column meta.

components/payments.tsxTSX
"use client"
import {
createColumnHelper,
tableFeatures,
useTable,
} from "@tanstack/react-table"
import { DataTable } from "@/components/cilo/data-table/data-table"
import {
DataTableColumnHeader,
sortingFeatures,
} from "@/components/cilo/data-table/data-table-column-header"
import {
DataTablePagination,
paginationFeatures,
} from "@/components/cilo/data-table/data-table-pagination"
import {
DataTableToolbar,
filteringFeatures,
} from "@/components/cilo/data-table/data-table-toolbar"
import { dataTableMeta } from "@/components/cilo/data-table/data-table-types"
type Payment = { id: string; email: string; status: string; amount: number }
const features = tableFeatures({
...dataTableMeta,
...sortingFeatures,
...filteringFeatures,
...paginationFeatures,
})
const columnHelper = createColumnHelper<typeof features, Payment>()
const columns = columnHelper.columns([
columnHelper.accessor("email", {
meta: { label: "Email" },
header: ({ column }) => <DataTableColumnHeader column={column} title="Email" />,
}),
columnHelper.accessor("status", { meta: { label: "Status" } }),
columnHelper.accessor("amount", {
meta: { label: "Amount", align: "end" },
header: ({ column }) => <DataTableColumnHeader column={column} title="Amount" />,
}),
])
export function Payments({ data }: { data: Payment[] }) {
const table = useTable({
features,
columns,
data,
getRowId: (row) => row.id,
})
return (
<div className="flex flex-col gap-4">
<DataTableToolbar table={table} search={{ columnId: "email" }} />
<DataTable table={table} />
<DataTablePagination table={table} />
</div>
)
}

Give the table getRowId when rows have ids of their own: selection, pinning, drag and drop and URL state keep their place by it.

Features and fragments

A part works when the table registers its features. Spread its fragment into tableFeatures; the server variants register the feature without the row model, for tables whose server sorts, filters or pages.

sortingFeatures
Sorting in the browser (column header). manualSortingFeatures with manualSorting for the server.
filteringFeatures
Column filters and the global filter (toolbar). manualFilteringFeatures with manualFiltering for the server.
paginationFeatures
Pages in the browser (pagination). manualPaginationFeatures with manualPagination and rowCount for the server.
selectionFeatures
Row selection (select column, action bar).
visibilityFeatures
Showing and hiding columns (view options, column header's Hide).
pinningFeatures
Column pinning with the column sizes its sticky offset needs (pin menu).
resizingFeatures
Column sizes and resizing (column resizer), with resizingOptions for live resizing.
expandingFeatures
Expanding rows into sub-rows or detail rows (expand column).
groupingFeatures
Grouping and aggregation (grouping menu).
rowPinningFeatures
Pinning rows to the top or bottom (row pinning).
multiSortFeatures
Sorting by several columns (sort menu).
columnOrderFeatures
Column order (column drag and drop).
cellSelectionFeatures
Spreadsheet-style cell ranges (cell selection).
editingFeatures
Editing one cell at a time (editable cell).
facetedFilterFeatures, toggleFilterFeatures, dateFilterFeatures, rangeFilterFeatures, booleanFilterFeatures, advancedFilterFeatures
Filtering with faceted counts for each filter control.

Column meta

Columns describe themselves in meta, typed by dataTableMeta. The core and every part read the same keys.

label
The column's name outside its header: in menus, filters, exports and as the head's accessible name.
align
start, center or end: the head, cells, footer and placeholder line up the same way.
rowHeader
The column names its rows: its cells are drawn as row headers (th scope="row").
filter
The control the toolbar draws for the column, set by a filter helper such as facetedFilter().
variant, options
What kind of values the column holds and the values an option column picks from, for the filter menu.
skeleton
What the loading body draws in the column instead of a stock Skeleton line.

A table with meta keys of its own declares metaHelper<Mine & DataTableColumnMeta>() in place of dataTableMeta; the filter helpers keep those keys.

Parts

Search and filters

data-table-toolbar
DataTableToolbar: a search box on one column, the filter each column declares, your own filters and actions, Reset while the filters differ from the table's initial ones, and the result count read out once filters settle. DataTableResultStatus is that count alone.
data-table-faceted-filter
DataTableFacetedFilter and facetedFilter(): several values of one column from a searchable list with counts.
data-table-toggle-filter
DataTableToggleFilter: one value of a column at a time as chips on a ToggleGroup, All first, each with its count. It stores the value as the faceted filter does, so the column takes filterFn_facets.
data-table-date-filter
DataTableDateFilter and dateRangeFilter(): a date range on the stock Calendar.
data-table-range-filter
DataTableRangeFilter and numberRangeFilter(): a number range on a two-thumb Slider with Min and Max inputs.
data-table-boolean-filter
DataTableBooleanFilter and booleanFilter(): All, Yes and No on a ToggleGroup.
data-table-filter-menu
DataTableFilterMenu and advancedFilter(): rules of column, operator and value for text, numbers, dates, options and booleans.
data-table-empty
DataTableEmptyState for a table with no rows yet; DataTableNoResults, passed as empty, with Clear filters.

Columns

data-table-column-header
DataTableColumnHeader: a header menu that sorts the column and hides it.
data-table-view-options
DataTableViewOptions: a View menu that shows and hides columns.
data-table-sort-menu
DataTableSortMenu: sort rules over several columns, reordered by drag or keyboard.
data-table-column-resizer
DataTableColumnResizer: a resize handle on a header's end edge, by pointer or arrow keys.
data-table-pin-menu
DataTableColumnPinMenu: pins a column to the start or end. Pinned columns that would leave the scroll container no room for an unpinned data column, as on a phone, are released and scroll with the rest until the room is back; their menus still say they are pinned.
data-table-column-dnd
DataTableColumnDnd and DataTableColumnDragHandle: columns reordered by drag or keyboard.

Rows

data-table-select-column
createSelectColumn: shadcn's checkbox column, select all on the page, parents mixed while only some sub-rows are selected.
data-table-action-bar
DataTableActionBar: bulk actions shown while rows are selected, with the count and Clear selection.
data-table-row-actions
DataTableRowActions and createActionsColumn: a row's menu built from a typed list of actions.
data-table-expand-column
createExpandColumn and DataTableExpandButton: open sub-rows or a detail row drawn by renderSubRow; the button takes aria-controls for the body it opens.
data-table-grouping
DataTableGroupingMenu and groupedCell: group by columns, expand and collapse groups.
data-table-row-pinning
DataTableRowPinButton and createRowPinColumn: pin rows to the top or bottom. Pinned rows that would leave less than a row's height under the sticky header are released the same way and scroll with the others until there is room again.
data-table-row-dnd
DataTableRowDnd and createDragHandleColumn: rows reordered by drag or keyboard; your onReorder moves the data.

Data and output

data-table-pagination
DataTablePagination: the selected count, rows per page, the page position and first, previous, next and last.
data-table-export
exportTableToCsv and DataTableExportButton: the rows the filters keep, or the selected ones, as a CSV guarded against spreadsheet formulas.
data-table-skeleton
DataTableSkeleton: placeholder rows while a server table fetches.
data-table-virtual-body
DataTableVirtualBody: only the rows in view, for long tables.
data-table-url-state
useDataTableUrlState: page, page size, sort, filters and search in the query string.
data-table-cell-selection
DataTableCellSelection: a grid with cell ranges, arrow keys and copy as tab-separated text.
data-table-editable-cell
editableCell(): edit a cell in place, as text, a number or a select, with validation.

Server-side tables

When the server sorts, filters and pages, spread the manual fragments, set the manual options and rowCount, and keep the state yourself to fetch with it. Pass your fetch state to the toolbar as loading, so the result count waits for the rows, and draw the skeleton meanwhile.

Server tableTSX
const table = useTable({
features: tableFeatures({
...dataTableMeta,
...manualSortingFeatures,
...manualFilteringFeatures,
...manualPaginationFeatures,
}),
columns,
data: page.rows,
manualSorting: true,
manualFiltering: true,
manualPagination: true,
rowCount: page.total,
state: { sorting, columnFilters, pagination },
onSortingChange: setSorting,
onColumnFiltersChange: setColumnFilters,
onPaginationChange: setPagination,
})
<DataTableToolbar table={table} search={{ columnId: "name" }} loading={fetching} />
<DataTable table={table}>
<DataTableHeader />
{fetching ? <DataTableSkeleton rows={pageSize} /> : <DataTableBody />}
</DataTable>
<DataTablePagination table={table} />

To keep the same state in the address bar, spread what useDataTableUrlState returns into useTable. It writes with history.replaceState or pushState, or a router's navigate you give it, and follows the back button.

URL stateTSX
const url = useDataTableUrlState()
const table = useTable({
features,
columns,
data,
...url,
})

Long tables

Put DataTableVirtualBody in place of DataTableBody and bound the table's height. Only the rows in view are drawn, the header stays sticky, and columns keep their widths.

Virtual rowsTSX
<DataTable table={table} stickyHeader>
<DataTableHeader />
<DataTableVirtualBody className="max-h-96" />
</DataTable>

Accessibility

  • The table stays a native table: rows, column and row headers, aria-sort on the first sorted column.
  • Heads with meta.label are named by it alone, not by the menus and handles drawn in them.
  • Filtering and searching read the result count out once it settles; loading reads “Loading…”.
  • Hide, Reset, Clear filters, unpinning and row actions move focus to a control that stays, never to the page.
  • Keyboard focus is scrolled clear of pinned columns, a sticky header, pinned rows and the action bar; focus a pointer press gives stays where it is.
  • Drag and drop, resizing and the sort menu work from the keyboard and announce each move.
  • Cell selection makes the table a grid with one tab stop, arrow keys, Home and End, mirrored right to left.

Styling

The table is the stock shadcn Table, so your style and palette apply as they do everywhere. To add classes or attributes of your own, pass components in the slots instead of class names: tableComponent for the table element, headerComponent, rowComponent and cellComponent for heads, rows and cells, or write them in the column's header and cell renderers. Define those components outside render.

frame={false}
Leaves out the rounded border, for a table inside a card or a pane.
stickyHeader
Keeps the header in view while the table scrolls inside a bounded height.
caption
Draws the stock TableCaption.
scrollLabel
Names the scrolling container and makes it focusable, so keys scroll it.
empty
What the body shows when no row is left; “No results.” by default.
onRowClick
A pointer shortcut on each row; keep a control in the row for the keyboard.

Troubleshooting

“Sorting, filtering or paging does nothing”
The table does not register the feature: spread the part's fragment (sortingFeatures, filteringFeatures, paginationFeatures …) into tableFeatures.
“A pinned column scrolls away”
Pinning sticks a column only with column sizes: spread pinningFeatures, which brings columnSizingFeature. In a narrow scroll container the release is on purpose: pinned columns that leave no room for an unpinned data column scroll with the rest, and stick again once the container is wide enough. Pinned rows that leave less than a row do the same.
“Selection or drag and drop jumps to the wrong row”
Give useTable getRowId, so rows keep their ids when the data is sorted, filtered or reloaded.
“My v8 tables stopped compiling”
The plugin installs TanStack Table v9; move those tables to v9's API, or meanwhile import useLegacyTable from @tanstack/react-table/legacy, which runs v8-style code (useReactTable options with the get*RowModel() stubs) on v9.