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:
npx shadcn@latest add @cilo/data-tablenpx 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:
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.
<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.
"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.
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.
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.
<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.