Data Table
newExcel called, it wants its features back. A table with sorting, sticky parts, pinned columns and rows, selection, trees, grouping, pagination, infinite scroll and row virtualization.
Open Props in the corner of the example to try size and loading.
Installation
Usage
<script setup lang="ts">
import { createDataTableColumnHelper, DataTable } from '@/components/ui/data-table'
type Payment = { id: string; email: string; amount: number }
const helper = createDataTableColumnHelper<Payment>()
const columns = helper.columns([
helper.accessor('email', { header: 'Email' }),
helper.accessor('amount', { header: 'Amount', size: 120, meta: { align: 'end' } }),
])
</script>
<template>
<DataTable :data="payments" :columns="columns" :get-row-id="(row) => row.id" sortable />
</template>
It runs on TanStack Table v9, which is why it installs @tanstack/vue-table. Build columns with createDataTableColumnHelper: it keeps columns, slots and state fully typed.
It's fast by design: cells are plain elements with Table's classes, not a component each. A thousand cells are a thousand elements, not a thousand component instances. Borders, --table-row-bg and the pinned-column shadow work just like in Table.
Examples
Columns and slots
A column's header, cell and footer can be a string, a function or a component. To take over in the template, use a slot: cell-<id>, header-<id> or footer-<id>. It gets the TanStack context: getValue, row, column and table.
Column meta takes:
align:start,centerorendtruncate: cuts long text with an ellipsis (needs a fixed layout)class,style: for thethandtd, as a value or a function of the context; footer cells take thetdones (astylefunction is left out there, since a footer has no row)
The toolbar slot renders above the table, outside the scroll.
Sorting
sortable gives every sortable column a header button that cycles ascending -> descending -> off. Shift-click adds a column to the sort.
{ multi: false }: one column at a time{ removable: false }: no "off" stepenableSorting: falseon a column: leave it out
v-model:sorting holds [{ id, desc }].
sortFn and filterFn take your own function, auto to pick one by the column's values, or the name of a built-in:
- sorting:
alphanumeric,alphanumericCaseSensitive,text,textCaseSensitive,datetime,basic - filtering:
includesString,includesStringSensitive,equalsString,equals,weakEquals,inNumberRange,inDateRange,arrIncludes,arrIncludesAll,arrIncludesSome
Need another TanStack built-in? Register it in dataTableFeatures in your copy.
Height, sticky parts and virtualization
height puts the table in a ScrollArea. The sticky header, the footer and pinned columns all share that one scroller. sticky sticks the header, the footer or both.
virtualize renders only the rows near the view: true always, "auto" from 200 rows, or an object with options. Rows keep a fixed height set by size. For rows of different heights, add measure: true.
It stays a real table, so colspan, sticky parts and screen reader row counts keep working.
Click a row.
Pinned columns
v-model:column-pinning takes { start: [...ids], end: [...ids] }.
Give pinned columns a size, since their offsets are computed from the widths. If every column has a size and the table is wider than their sum, an extra filler column takes the rest. The outermost pinned column casts a shadow while content can scroll under it.
Pagination
paginate splits the rows into pages and adds DataTablePagination under the table. v-model:pagination holds { pageIndex, pageSize }. When the rows change, it goes back to the first page.
1–8 of 45
Server mode
Data lives on the server? manual hands the work to you: all of it, or per feature with { sorting, filtering, pagination, expanding }. The table shows data as is and reports the state through the models.
- Pass
rowCount, so it knows how many pages there are. Without it, the bar shows only Previous and Next. - The page doesn't reset on its own here: do it yourself when filters change.
1–10 of 500
Loading, empty and error
loading shows a progress bar under the header, and the rows you have stay in place. No rows yet? Skeleton rows fill the height instead.
No rows and not loading: the empty message shows, or noResults when a filter is on.
error takes over the body: the rows, the skeleton and the empty message give way to it, and infinite scroll waits until it clears. Pass the error itself, :error="query.error.value"; the error slot gets it as { error }, and an ErrorState with a Retry button fits there. Without the slot, a string shows as the message and anything else as "Something went wrong". With loading on as well, as during a retry, the error stays and the progress bar runs.
Row events
Pass onRowClick, onRowContextmenu or onRowHover (or @row-click and friends), and rows become clickable: focusable, with a pointer cursor, and they fire on Enter and Space too. Clicks on buttons and inputs inside a row don't count as row clicks.
A clickable row isn't a button for screen readers, so put the same action on a control inside the row too.
Row actions
Add a display column with a cell-<id> slot. Inside, wrap an icon button in MenuTrigger with as-child, and the Menu next to it opens from that button. row.original is right there for the items, and a click on the button isn't a row click.
Open a row's menu.
Selection
selection adds a checkbox column:
trueor"multiple": many rows"single": one row- an object,
{ mode, column, enableRowSelection, selectAll }:column: falsehides the column, andenableRowSelectiondecides per row
v-model:row-selection holds { [id]: true }. Shift-click selects a range.
Need to know where a change came from? update:rowSelection gets a second argument, { source }: header, row, range or imperative.
Select all, Gmail style. With pagination, the header checkbox selects the current page, and a banner offers to select the rest. v-model:select-all goes none -> page -> all.
In all, every row on every page counts as selected, and the model stores only the exceptions, as { [id]: false }. For the request to your server, getSelection() returns { mode, ids, excluded, count }.
- Unchecking a row in
pagedrops back tonone. - In server mode, a sort or filter change drops
allback tonone: the rows the user agreed to are gone.
selectAllLabels changes the banner text, and the select-all-banner slot replaces the banner entirely. selectAll: false turns it off. Without pagination, the header checkbox just selects every filtered row, with no banner.
1–8 of 45
0 selected
Expanding and trees
expandable adds a chevron column. Add an expanded slot, and each row opens a detail row under it. Hover and selection tint both together. With virtualization, measure turns on by itself.
v-model:expanded holds { [id]: true }, or true for every row. table.toggleAllRowsExpanded() toggles them all, and getRowCanExpand decides per row.
For a tree, pass getSubRows: children render as regular rows, indented by depth. They paginate with the rest; paginateExpandedRows: false keeps them on their parent's page.
Grouping
groupable with v-model:grouping groups rows by column ids, in order. Grouped columns move to the front.
A group row shows a toggle, the value and the row count. Other columns show their aggregatedCell, computed by the column's aggregationFn: sum, min, max, extent, mean, median, unique, uniqueCount, count, first, last, or your own function.
Groups open and close through the expanded model, like tree rows.
Pinned rows
v-model:row-pinning takes { top: [...ids], bottom: [...ids] }. Pinned rows stick under the header and above the footer, never get virtualized away, and stay even when a filter hides them. From a cell, row.pin('top'), row.pin('bottom') and row.pin(false) toggle them.
Infinite scroll
Doomscrolling, table edition. onLoadMore (or @load-more) loads more rows as you near an edge. It gets { direction, index }, with index starting at 1, and should resolve once the new rows are in data.
Out of rows? Resolve 'stop'. To pause and resume, use hasMore: false, or { top, bottom } per edge.
loadMore options:
direction:bottom,toporboththreshold: how close to the edge to start loading; rows with virtualization (the overscan by default), pixels without it (200 by default)initialFill: keep loading until the table overflows
Loading at the top keeps your reading position. The loadingMore slot shows at the loading edge (a spinner by default), and endOfData shows once there's nothing left. In server mode, a sort or filter change restarts index at 1.
It watches the table's own scroll area, or the nearest scrolling parent, or the window, and runs on useInfiniteScroll. Don't combine it with server-side pagination: the table warns in development.
State
Every TanStack state slice is a v-model: on the component: sorting, column-visibility, column-pinning, column-order, column-sizing, column-filters, global-filter, pagination, row-selection, expanded, grouping and row-pinning, plus the table's own select-all.
Don't bind a model, and the table keeps it inside. Bind it, and yours becomes the only source, even if it starts as undefined. Starting values for either go in tableOptions.initialState.
Known limits
- Mutating
datain place goes unnoticed. Pass a new array. - Without
height,overflow="x"breaks the sticky header. For a header that sticks to the page, useoverflow="visible". - Browsers can lay out about 16 million pixels of height. Past that, paginate on the server. The table warns in development.
- A pinned column without a
sizegets 150px and a warning in development. - There's no
maxHeightyet, so give the table aheight. Column resizing is coming next.
API Reference
class goes on the root.
DataTable
| Prop | Default | Type and description |
|---|---|---|
| data* | — | readonly T[]The rows. Pass a new array to change them; a mutation in place is not seen (one warning in development). |
| columns | — | readonly DataTableColumn<T>[]TanStack column definitions, best made with |
| getRowId | — | ((originalRow: T, index: number, parent?: Row<{ columnFilteringFeature: TableFeature; columnGroupingFeature: TableFeature; columnOrderingFeature: TableFeature; columnPinningFeature: TableFeature; columnResizingFeature: TableFeature; columnSizingFeature: TableFeature; columnVisibilityFeature: TableFeature; globalFilteringFeature: TableFeature; rowAggregationFeature: TableFeature; rowExpandingFeature: TableFeature; rowPaginationFeature: TableFeature; rowPinningFeature: TableFeature; rowSelectionFeature: TableFeature; rowSortingFeature: TableFeature; expandedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; filteredRowModel: (table: Table<any, any>) => () => RowModel<any, any>; groupedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; paginatedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortFns: { alphanumeric: CreatedSortFn<any, any>; alphanumericCaseSensitive: CreatedSortFn<any, any>; text: CreatedSortFn<any, any>; textCaseSensitive: CreatedSortFn<any, any>; datetime: CreatedSortFn<any, any>; basic: CreatedSortFn<any, any>; }; filterFns: { includesString: CreatedFilterFn<any, any>; includesStringSensitive: CreatedFilterFn<any, any>; equalsString: CreatedFilterFn<any, any>; equals: CreatedFilterFn<any, any>; weakEquals: CreatedFilterFn<any, any>; inNumberRange: CreatedFilterFn<any, any>; inDateRange: CreatedFilterFn<any, any>; arrIncludes: CreatedFilterFn<any, any>; arrIncludesAll: CreatedFilterFn<any, any>; arrIncludesSome: CreatedFilterFn<any, any>; }; aggregationFns: { sum: AggregationFnDef<any, any, unknown, number>; min: AggregationFnDef<any, any, unknown, RangeValue | undefined>; max: AggregationFnDef<any, any, unknown, RangeValue | undefined>; extent: AggregationFnDef<any, any, unknown, [RangeValue | undefined, RangeValue | undefined]>; mean: AggregationFnDef<any, any, unknown, number | undefined>; median: AggregationFnDef<any, any, unknown, number | undefined>; unique: AggregationFnDef<any, any, unknown, unknown[]>; uniqueCount: AggregationFnDef<any, any, unknown, number>; count: AggregationFnDef<any, any, unknown, number>; first: AggregationFnDef<any, any, unknown, unknown>; last: AggregationFnDef<any, any, unknown, unknown>; }; columnMeta: DataTableColumnMeta; }, T> | undefined) => string)Returns a stable id for a row. Without it the id is the index, and selection or expansion moves when the rows are sorted or replaced. |
| getSubRows | — | ((row: T) => readonly T[] | undefined)Returns a row's children, for a tree; with |
| caption | — | stringA caption read by assistive technology, visually hidden. |
| size | "md" | TableSizeRow height, |
| striped | false | booleanTints every even row by its absolute index, so virtualization does not break the pattern. |
| hoverable | true | booleanHover tint on body rows. On by default; |
| height | — | string | numberPuts the table in a scroll area of this height, scrolling on both axes; needed for sticky parts and virtualization. A number is pixels. |
| overflow | "x" | TableOverflowWithout |
| sticky | false | boolean | "footer" | "header"Sticks the header, the footer, or both ( |
| virtualize | false | DataTableVirtualizeRenders only the rows near the view. |
| sortable | — | DataTableSortingPropLets columns sort through a header button. |
| paginate | — | DataTablePaginationPropPaginates and renders |
| selection | — | DataTableSelectionPropPrepends a checkbox column and lets rows be selected. |
| selectAllLabels | — | Partial<DataTableSelectAllLabels>The banner texts, |
| rowSelection | — | DataTableRowSelectionState
|
| expandable | — | DataTableExpandingPropPrepends a chevron column and lets rows expand, into the |
| groupable | — | booleanLets |
| manual | — | DataTableManualLeaves sorting, filtering, pagination or expanding to the server, |
| rowCount | — | numberThe total number of rows in manual pagination. Without it the page count is unknown and the bar shows previous and next only. |
| columnResizing | — | booleanReserved; accepted and ignored until column resizing lands. |
| loading | false | booleanShows an indeterminate progress bar under the header and, with no data, skeleton rows. |
| loadingRows | — | numberHow many skeleton rows to show while loading with no data. By default as many as fit the height, or five. |
| empty | "No data" | stringThe message when there are no rows and no filter is active. |
| noResults | "No results" | stringThe message when a filter leaves no rows. |
| error | — | unknownShows the error state in place of the rows, the skeleton and the empty message, and pauses infinite scroll. Any value but |
| onLoadMore | — | DataTableLoadMoreFnLoads more rows when the scroller nears an edge (bind it as |
| hasMore | true | DataTableHasMoreWhether more rows can load, |
| loadMore | — | DataTableLoadMoreInfinite scroll settings: |
| onRowClick | — | DataTableRowEvent<T>Makes rows clickable ( |
| onRowContextmenu | — | DataTableRowEvent<T>Receives the |
| onRowHover | — | ((event: MouseEvent, row: DataTableRow<T> | null) => void)Receives the pointer event and the row on enter, and |
| tableOptions | — | Partial<TableOptions<{ columnFilteringFeature: TableFeature; columnGroupingFeature: TableFeature; columnOrderingFeature: TableFeature; columnPinningFeature: TableFeature; columnResizingFeature: TableFeature; columnSizingFeature: TableFeature; columnVisibilityFeature: TableFeature; globalFilteringFeature: TableFeature; rowAggregationFeature: TableFeature; rowExpandingFeature: TableFeature; rowPaginationFeature: TableFeature; rowPinningFeature: TableFeature; rowSelectionFeature: TableFeature; rowSortingFeature: TableFeature; expandedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; filteredRowModel: (table: Table<any, any>) => () => RowModel<any, any>; groupedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; paginatedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortFns: { alphanumeric: CreatedSortFn<any, any>; alphanumericCaseSensitive: CreatedSortFn<any, any>; text: CreatedSortFn<any, any>; textCaseSensitive: CreatedSortFn<any, any>; datetime: CreatedSortFn<any, any>; basic: CreatedSortFn<any, any>; }; filterFns: { includesString: CreatedFilterFn<any, any>; includesStringSensitive: CreatedFilterFn<any, any>; equalsString: CreatedFilterFn<any, any>; equals: CreatedFilterFn<any, any>; weakEquals: CreatedFilterFn<any, any>; inNumberRange: CreatedFilterFn<any, any>; inDateRange: CreatedFilterFn<any, any>; arrIncludes: CreatedFilterFn<any, any>; arrIncludesAll: CreatedFilterFn<any, any>; arrIncludesSome: CreatedFilterFn<any, any>; }; aggregationFns: { sum: AggregationFnDef<any, any, unknown, number>; min: AggregationFnDef<any, any, unknown, RangeValue | undefined>; max: AggregationFnDef<any, any, unknown, RangeValue | undefined>; extent: AggregationFnDef<any, any, unknown, [RangeValue | undefined, RangeValue | undefined]>; mean: AggregationFnDef<any, any, unknown, number | undefined>; median: AggregationFnDef<any, any, unknown, number | undefined>; unique: AggregationFnDef<any, any, unknown, unknown[]>; uniqueCount: AggregationFnDef<any, any, unknown, number>; count: AggregationFnDef<any, any, unknown, number>; first: AggregationFnDef<any, any, unknown, unknown>; last: AggregationFnDef<any, any, unknown, unknown>; }; columnMeta: DataTableColumnMeta; }, T>>Passed to TanStack's |
| ui | — | Partial<Record<DataTableSlot, ClassValue>>Classes per part, merged over the base classes; the keys are |
| sorting | — | SortingState
|
| columnVisibility | — | ColumnVisibilityState
|
| columnPinning | — | ColumnPinningState
|
| columnOrder | — | ColumnOrderState
|
| columnSizing | — | ColumnSizingState
|
| columnFilters | — | ColumnFiltersState
|
| globalFilter | — | string
|
| pagination | — | PaginationState
|
| selectAll | "none" | DataTableSelectAll
|
| expanded | — | ExpandedState
|
| grouping | — | GroupingState
|
| rowPinning | — | RowPinningState
|
| Event | Payload and description |
|---|---|
| update:rowSelection | [state: DataTableRowSelectionState, details: { source: DataTableSelectionSource; }]The row selection changed. The second argument is |
| update:sorting | [value: SortingState | undefined]The sorting state changed. |
| update:columnVisibility | [value: ColumnVisibilityState | undefined]The column visibility changed. |
| update:columnPinning | [value: ColumnPinningState | undefined]The column pinning changed. |
| update:columnOrder | [value: ColumnOrderState | undefined]The column order changed. |
| update:columnSizing | [value: ColumnSizingState | undefined]The column sizing changed. |
| update:columnFilters | [value: ColumnFiltersState | undefined]The column filters changed. |
| update:globalFilter | [value: string | undefined]The global filter changed. |
| update:pagination | [value: PaginationState | undefined]The page index or size changed. |
| update:selectAll | [value: DataTableSelectAll]The select-all mode changed. |
| update:expanded | [value: ExpandedState | undefined]The expanded rows changed. |
| update:grouping | [value: GroupingState | undefined]The grouping changed. |
| update:rowPinning | [value: RowPinningState | undefined]The row pinning changed. |
| Slot | Scope and description |
|---|---|
| toolbar | { table: DataTableInstance<T>; }Rendered above the table, outside the scroller, with |
| caption | anyThe caption's content, in place of the |
| empty | anyThe message when there are no rows. |
| noResults | anyThe message when a filter leaves no rows. |
| error | { error: unknown; }The error state, with |
| expanded | { row: DataTableRow<T>; }The detail row of an expanded row, with |
| loadingMore | { direction: DataTableLoadDirection; }What shows at the loading edge while more rows load, with |
| endOfData | { direction: DataTableLoadDirection; }What shows at an edge once it has no more rows, with |
| select-all-banner | { pageCount: number; totalCount: number; mode: DataTableSelectAll; selectAll: () => void; clear: () => void; }Replaces the banner under the toolbar, with |
| Member | Type and description |
|---|---|
| table | DataTableInstance<T>The TanStack table instance. |
| scrollToIndex | (index: number, options?: DataTableScrollOptions | undefined) => voidScrolls a row index into view; |
| scrollToRow | (id: string, options?: DataTableScrollOptions | undefined) => booleanScrolls a row id into view and returns whether it is in the current rows. |
| focusRow | (index: number) => voidScrolls a row index into view and focuses it. |
| measure | () => voidDrops the measured row heights and measures again. |
| getSelection | () => DataTableSelectionThe selection for a request: |
DataTableColumnHeader
| Prop | Default | Type and description |
|---|---|---|
| header* | — | Header<{ columnFilteringFeature: TableFeature; columnGroupingFeature: TableFeature; columnOrderingFeature: TableFeature; columnPinningFeature: TableFeature; columnResizingFeature: TableFeature; columnSizingFeature: TableFeature; columnVisibilityFeature: TableFeature; globalFilteringFeature: TableFeature; rowAggregationFeature: TableFeature; rowExpandingFeature: TableFeature; rowPaginationFeature: TableFeature; rowPinningFeature: TableFeature; rowSelectionFeature: TableFeature; rowSortingFeature: TableFeature; expandedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; filteredRowModel: (table: Table<any, any>) => () => RowModel<any, any>; groupedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; paginatedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortFns: { alphanumeric: CreatedSortFn<any, any>; alphanumericCaseSensitive: CreatedSortFn<any, any>; text: CreatedSortFn<any, any>; textCaseSensitive: CreatedSortFn<any, any>; datetime: CreatedSortFn<any, any>; basic: CreatedSortFn<any, any>; }; filterFns: { includesString: CreatedFilterFn<any, any>; includesStringSensitive: CreatedFilterFn<any, any>; equalsString: CreatedFilterFn<any, any>; equals: CreatedFilterFn<any, any>; weakEquals: CreatedFilterFn<any, any>; inNumberRange: CreatedFilterFn<any, any>; inDateRange: CreatedFilterFn<any, any>; arrIncludes: CreatedFilterFn<any, any>; arrIncludesAll: CreatedFilterFn<any, any>; arrIncludesSome: CreatedFilterFn<any, any>; }; aggregationFns: { sum: AggregationFnDef<any, any, unknown, number>; min: AggregationFnDef<any, any, unknown, RangeValue | undefined>; max: AggregationFnDef<any, any, unknown, RangeValue | undefined>; extent: AggregationFnDef<any, any, unknown, [RangeValue | undefined, RangeValue | undefined]>; mean: AggregationFnDef<any, any, unknown, number | undefined>; median: AggregationFnDef<any, any, unknown, number | undefined>; unique: AggregationFnDef<any, any, unknown, unknown[]>; uniqueCount: AggregationFnDef<any, any, unknown, number>; count: AggregationFnDef<any, any, unknown, number>; first: AggregationFnDef<any, any, unknown, unknown>; last: AggregationFnDef<any, any, unknown, unknown>; }; columnMeta: DataTableColumnMeta; }, T, unknown>The TanStack header to render. A ghost button with the column's header, its sort direction and, in a multi-sort, its rank. |
DataTablePagination
| Prop | Default | Type and description |
|---|---|---|
| table* | — | DataTableInstance<T>The TanStack table whose pagination state to show and change. With an unknown page count it shows previous and next only. |
DataTableSelectAllBanner
| Prop | Default | Type and description |
|---|---|---|
| mode* | — | DataTableSelectAll
|
| pageCount* | — | numberHow many rows of the page are selected. |
| totalCount* | — | numberHow many rows there are in all, across pages. |
| labels | — | Partial<DataTableSelectAllLabels>Overrides for the texts, |
| Event | Payload and description |
|---|---|
| selectAll | []The select-all link was pressed. |
| clear | []The clear link was pressed. |
DataTableSelectCell
| Prop | Default | Type and description |
|---|---|---|
| row* | — | DataTableRow<T>The TanStack row. A checkbox that toggles it, selects a range with Shift, and is disabled when the row cannot be selected. |
DataTableExpandCell
| Prop | Default | Type and description |
|---|---|---|
| row* | — | DataTableRow<T>The TanStack row. A chevron button that toggles it when it can expand, indented by the row's depth. |
DataTableGroupCell
| Prop | Default | Type and description |
|---|---|---|
| row* | — | DataTableRow<T>The grouped TanStack row. A chevron button that toggles the group, the value and the number of leaf rows. |
| Slot | Scope and description |
|---|---|
| default | {}The group's value, the column's cell by default. |
DataTableSelectHeader
No props, events, slots or exposed members.
Props
- data*
readonly T[]The rows. Pass a new array to change them; a mutation in place is not seen (one warning in development).- columns
readonly DataTableColumn<T>[]TanStack column definitions, best made withcreateDataTableColumnHelper. Left out, one column per key of the first row.- getRowId
((originalRow: T, index: number, parent?: Row<{ columnFilteringFeature: TableFeature; columnGroupingFeature: TableFeature; columnOrderingFeature: TableFeature; columnPinningFeature: TableFeature; columnResizingFeature: TableFeature; columnSizingFeature: TableFeature; columnVisibilityFeature: TableFeature; globalFilteringFeature: TableFeature; rowAggregationFeature: TableFeature; rowExpandingFeature: TableFeature; rowPaginationFeature: TableFeature; rowPinningFeature: TableFeature; rowSelectionFeature: TableFeature; rowSortingFeature: TableFeature; expandedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; filteredRowModel: (table: Table<any, any>) => () => RowModel<any, any>; groupedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; paginatedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortFns: { alphanumeric: CreatedSortFn<any, any>; alphanumericCaseSensitive: CreatedSortFn<any, any>; text: CreatedSortFn<any, any>; textCaseSensitive: CreatedSortFn<any, any>; datetime: CreatedSortFn<any, any>; basic: CreatedSortFn<any, any>; }; filterFns: { includesString: CreatedFilterFn<any, any>; includesStringSensitive: CreatedFilterFn<any, any>; equalsString: CreatedFilterFn<any, any>; equals: CreatedFilterFn<any, any>; weakEquals: CreatedFilterFn<any, any>; inNumberRange: CreatedFilterFn<any, any>; inDateRange: CreatedFilterFn<any, any>; arrIncludes: CreatedFilterFn<any, any>; arrIncludesAll: CreatedFilterFn<any, any>; arrIncludesSome: CreatedFilterFn<any, any>; }; aggregationFns: { sum: AggregationFnDef<any, any, unknown, number>; min: AggregationFnDef<any, any, unknown, RangeValue | undefined>; max: AggregationFnDef<any, any, unknown, RangeValue | undefined>; extent: AggregationFnDef<any, any, unknown, [RangeValue | undefined, RangeValue | undefined]>; mean: AggregationFnDef<any, any, unknown, number | undefined>; median: AggregationFnDef<any, any, unknown, number | undefined>; unique: AggregationFnDef<any, any, unknown, unknown[]>; uniqueCount: AggregationFnDef<any, any, unknown, number>; count: AggregationFnDef<any, any, unknown, number>; first: AggregationFnDef<any, any, unknown, unknown>; last: AggregationFnDef<any, any, unknown, unknown>; }; columnMeta: DataTableColumnMeta; }, T> | undefined) => string)Returns a stable id for a row. Without it the id is the index, and selection or expansion moves when the rows are sorted or replaced.- getSubRows
((row: T) => readonly T[] | undefined)Returns a row's children, for a tree; withexpandablethey render as rows of their own, indented by depth.- caption
stringA caption read by assistive technology, visually hidden.- size
"md" TableSizeRow height,xstoxlas onTable, through the table's--table-row-h; also the estimated row height while virtualizing. Atxsthe sort buttons and the expand and group toggles shrink so they fit in the 28px row.- striped
false booleanTints every even row by its absolute index, so virtualization does not break the pattern.- hoverable
true booleanHover tint on body rows. On by default;falsemakes--table-hover-bgtransparent.- height
string | numberPuts the table in a scroll area of this height, scrolling on both axes; needed for sticky parts and virtualization. A number is pixels.- overflow
"x" TableOverflowWithoutheight,xwraps the table in a container that scrolls sideways andvisibleclips nothing, so a sticky header sticks to the page.- sticky
false boolean | "footer" | "header"Sticks the header, the footer, or both (true) to the scroll area.- virtualize
false DataTableVirtualizeRenders only the rows near the view.true, or"auto"to switch on from 200 rows, or an object withenabled,threshold,estimateSize,measure,overscan,getScrollElementandscrollMargin. NeedsheightorgetScrollElement.- sortable
DataTableSortingPropLets columns sort through a header button.true, or{ multi, removable, sortDescFirst }.- paginate
DataTablePaginationPropPaginates and rendersDataTablePaginationunder the table.truefor ten rows a page, or{ pageSize }.- selection
DataTableSelectionPropPrepends a checkbox column and lets rows be selected.trueor"multiple","single"for one row at a time, or{ mode, column, enableRowSelection, selectAll };column: falsekeeps the column out,enableRowSelectiondecides per row,selectAllswitches the page and select-all machine, on by default withpaginate.- selectAllLabels
Partial<DataTableSelectAllLabels>The banner texts,{ page(count), all(total), selected(total), clear }, each a function of the count or a string; English by default.- rowSelection
DataTableRowSelectionStatev-model:row-selection,{ [id]: true }for selected rows and, whileselectAllisall,{ [id]: false }for the rows taken out.- expandable
DataTableExpandingPropPrepends a chevron column and lets rows expand, into theexpandedslot's detail row or into theirgetSubRowschildren.true, or{ column, getRowCanExpand, paginateExpandedRows };paginateExpandedRows: falsekeeps children on their parent's page.- groupable
booleanLetsv-model:groupinggroup the rows by columns; grouped rows show a toggle, the value and the leaf count, and the other columns'aggregatedCell.- manual
DataTableManualLeaves sorting, filtering, pagination or expanding to the server,truefor all or an object per feature; the table then showsdataas it is and only reports the state.- rowCount
numberThe total number of rows in manual pagination. Without it the page count is unknown and the bar shows previous and next only.- columnResizing
booleanReserved; accepted and ignored until column resizing lands.- loading
false booleanShows an indeterminate progress bar under the header and, with no data, skeleton rows.- loadingRows
numberHow many skeleton rows to show while loading with no data. By default as many as fit the height, or five.- empty
"No data" stringThe message when there are no rows and no filter is active.- noResults
"No results" stringThe message when a filter leaves no rows.- error
unknownShows the error state in place of the rows, the skeleton and the empty message, and pauses infinite scroll. Any value butundefined,nullandfalsecounts, so pass the error itself; a string is the default message.- onLoadMore
DataTableLoadMoreFnLoads more rows when the scroller nears an edge (bind it as@load-moretoo). Receives{ direction, index },indexcounting loads in that direction from 1; resolve once the rows are indata, resolve'stop'when there are no more, and a rejection rolls the index back and reports the error.- hasMore
true DataTableHasMoreWhether more rows can load,trueby default;false, or{ top, bottom }per direction, pauses loading until it turns true again.- loadMore
DataTableLoadMoreInfinite scroll settings:direction(bottom,toporboth),threshold(rows under virtualization, by default the overscan; pixels otherwise, 200 by default) andinitialFill(keep loading while the rows do not fill the height, on by default).- onRowClick
DataTableRowEvent<T>Makes rows clickable (tabindex="0",data-clickable) and receives the event and the row; also fires on Enter and Space. Clicks on controls inside the row are not row clicks.- onRowContextmenu
DataTableRowEvent<T>Receives thecontextmenuevent and the row.- onRowHover
((event: MouseEvent, row: DataTableRow<T> | null) => void)Receives the pointer event and the row on enter, andnullon leave.- tableOptions
Partial<TableOptions<{ columnFilteringFeature: TableFeature; columnGroupingFeature: TableFeature; columnOrderingFeature: TableFeature; columnPinningFeature: TableFeature; columnResizingFeature: TableFeature; columnSizingFeature: TableFeature; columnVisibilityFeature: TableFeature; globalFilteringFeature: TableFeature; rowAggregationFeature: TableFeature; rowExpandingFeature: TableFeature; rowPaginationFeature: TableFeature; rowPinningFeature: TableFeature; rowSelectionFeature: TableFeature; rowSortingFeature: TableFeature; expandedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; filteredRowModel: (table: Table<any, any>) => () => RowModel<any, any>; groupedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; paginatedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortFns: { alphanumeric: CreatedSortFn<any, any>; alphanumericCaseSensitive: CreatedSortFn<any, any>; text: CreatedSortFn<any, any>; textCaseSensitive: CreatedSortFn<any, any>; datetime: CreatedSortFn<any, any>; basic: CreatedSortFn<any, any>; }; filterFns: { includesString: CreatedFilterFn<any, any>; includesStringSensitive: CreatedFilterFn<any, any>; equalsString: CreatedFilterFn<any, any>; equals: CreatedFilterFn<any, any>; weakEquals: CreatedFilterFn<any, any>; inNumberRange: CreatedFilterFn<any, any>; inDateRange: CreatedFilterFn<any, any>; arrIncludes: CreatedFilterFn<any, any>; arrIncludesAll: CreatedFilterFn<any, any>; arrIncludesSome: CreatedFilterFn<any, any>; }; aggregationFns: { sum: AggregationFnDef<any, any, unknown, number>; min: AggregationFnDef<any, any, unknown, RangeValue | undefined>; max: AggregationFnDef<any, any, unknown, RangeValue | undefined>; extent: AggregationFnDef<any, any, unknown, [RangeValue | undefined, RangeValue | undefined]>; mean: AggregationFnDef<any, any, unknown, number | undefined>; median: AggregationFnDef<any, any, unknown, number | undefined>; unique: AggregationFnDef<any, any, unknown, unknown[]>; uniqueCount: AggregationFnDef<any, any, unknown, number>; count: AggregationFnDef<any, any, unknown, number>; first: AggregationFnDef<any, any, unknown, unknown>; last: AggregationFnDef<any, any, unknown, unknown>; }; columnMeta: DataTableColumnMeta; }, T>>Passed to TanStack'suseTableunder the table's own options, forinitialState,defaultColumn,metaand the like.- ui
Partial<Record<DataTableSlot, ClassValue>>Classes per part, merged over the base classes; the keys areroot,scroll,table,caption,thead,tbody,tfoot,tr,th,td,spacer,filler,empty,error,loading,skeleton,pagination,banner,expanded,pinned,loadingMoreandendOfData.- sorting
SortingStatev-model:sorting, the sorting state. Every state model is local until it is bound.- columnVisibility
ColumnVisibilityStatev-model:column-visibility.- columnPinning
ColumnPinningStatev-model:column-pinning,{ start, end }of column ids.- columnOrder
ColumnOrderStatev-model:column-order.- columnSizing
ColumnSizingStatev-model:column-sizing.- columnFilters
ColumnFiltersStatev-model:column-filters.- globalFilter
stringv-model:global-filter, a string matched against every column.- pagination
PaginationStatev-model:pagination,{ pageIndex, pageSize }.- selectAll
"none" DataTableSelectAllv-model:select-all, the select-all mode:none,pageafter the header checkbox selected the page,allafter the banner selected every row.- expanded
ExpandedStatev-model:expanded,{ [id]: true }for the expanded rows, ortruefor all of them.- grouping
GroupingStatev-model:grouping, the ids of the columns grouped by, in order.- rowPinning
RowPinningStatev-model:row-pinning,{ top, bottom }of row ids; pinned rows render in sticky row groups outside the virtualized window.
Emits
- update:rowSelection
[state: DataTableRowSelectionState, details: { source: DataTableSelectionSource; }]The row selection changed. The second argument is{ source }:headerfor the header checkbox and the banner,rowfor a row checkbox,rangefor a shift-click,imperativefor a call on the table.- update:sorting
[value: SortingState | undefined]The sorting state changed.- update:columnVisibility
[value: ColumnVisibilityState | undefined]The column visibility changed.- update:columnPinning
[value: ColumnPinningState | undefined]The column pinning changed.- update:columnOrder
[value: ColumnOrderState | undefined]The column order changed.- update:columnSizing
[value: ColumnSizingState | undefined]The column sizing changed.- update:columnFilters
[value: ColumnFiltersState | undefined]The column filters changed.- update:globalFilter
[value: string | undefined]The global filter changed.- update:pagination
[value: PaginationState | undefined]The page index or size changed.- update:selectAll
[value: DataTableSelectAll]The select-all mode changed.- update:expanded
[value: ExpandedState | undefined]The expanded rows changed.- update:grouping
[value: GroupingState | undefined]The grouping changed.- update:rowPinning
[value: RowPinningState | undefined]The row pinning changed.
Slots
- toolbar
{ table: DataTableInstance<T>; }Rendered above the table, outside the scroller, with{ table }.- caption
anyThe caption's content, in place of thecaptionprop.- empty
anyThe message when there are no rows.- noResults
anyThe message when a filter leaves no rows.- error
{ error: unknown; }The error state, with{ error }. An alert with theerrorstring orSomething went wrongby default; put anErrorStatehere.- expanded
{ row: DataTableRow<T>; }The detail row of an expanded row, with{ row }; rendered inside the row's group, spanning every column.- loadingMore
{ direction: DataTableLoadDirection; }What shows at the loading edge while more rows load, with{ direction }; a spinner row by default.- endOfData
{ direction: DataTableLoadDirection; }What shows at an edge once it has no more rows, with{ direction }.- select-all-banner
{ pageCount: number; totalCount: number; mode: DataTableSelectAll; selectAll: () => void; clear: () => void; }Replaces the banner under the toolbar, with{ pageCount, totalCount, mode, selectAll, clear }.
Exposed
- table
DataTableInstance<T>The TanStack table instance.- scrollToIndex
(index: number, options?: DataTableScrollOptions | undefined) => voidScrolls a row index into view;alignisstart,center,endorauto.- scrollToRow
(id: string, options?: DataTableScrollOptions | undefined) => booleanScrolls a row id into view and returns whether it is in the current rows.- focusRow
(index: number) => voidScrolls a row index into view and focuses it.- measure
() => voidDrops the measured row heights and measures again.- getSelection
() => DataTableSelectionThe selection for a request:{ mode, ids, excluded, count }, whereallmode lists the excluded ids instead of the selected ones.
Props
- header*
Header<{ columnFilteringFeature: TableFeature; columnGroupingFeature: TableFeature; columnOrderingFeature: TableFeature; columnPinningFeature: TableFeature; columnResizingFeature: TableFeature; columnSizingFeature: TableFeature; columnVisibilityFeature: TableFeature; globalFilteringFeature: TableFeature; rowAggregationFeature: TableFeature; rowExpandingFeature: TableFeature; rowPaginationFeature: TableFeature; rowPinningFeature: TableFeature; rowSelectionFeature: TableFeature; rowSortingFeature: TableFeature; expandedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; filteredRowModel: (table: Table<any, any>) => () => RowModel<any, any>; groupedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; paginatedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortedRowModel: (table: Table<any, any>) => () => RowModel<any, any>; sortFns: { alphanumeric: CreatedSortFn<any, any>; alphanumericCaseSensitive: CreatedSortFn<any, any>; text: CreatedSortFn<any, any>; textCaseSensitive: CreatedSortFn<any, any>; datetime: CreatedSortFn<any, any>; basic: CreatedSortFn<any, any>; }; filterFns: { includesString: CreatedFilterFn<any, any>; includesStringSensitive: CreatedFilterFn<any, any>; equalsString: CreatedFilterFn<any, any>; equals: CreatedFilterFn<any, any>; weakEquals: CreatedFilterFn<any, any>; inNumberRange: CreatedFilterFn<any, any>; inDateRange: CreatedFilterFn<any, any>; arrIncludes: CreatedFilterFn<any, any>; arrIncludesAll: CreatedFilterFn<any, any>; arrIncludesSome: CreatedFilterFn<any, any>; }; aggregationFns: { sum: AggregationFnDef<any, any, unknown, number>; min: AggregationFnDef<any, any, unknown, RangeValue | undefined>; max: AggregationFnDef<any, any, unknown, RangeValue | undefined>; extent: AggregationFnDef<any, any, unknown, [RangeValue | undefined, RangeValue | undefined]>; mean: AggregationFnDef<any, any, unknown, number | undefined>; median: AggregationFnDef<any, any, unknown, number | undefined>; unique: AggregationFnDef<any, any, unknown, unknown[]>; uniqueCount: AggregationFnDef<any, any, unknown, number>; count: AggregationFnDef<any, any, unknown, number>; first: AggregationFnDef<any, any, unknown, unknown>; last: AggregationFnDef<any, any, unknown, unknown>; }; columnMeta: DataTableColumnMeta; }, T, unknown>The TanStack header to render. A ghost button with the column's header, its sort direction and, in a multi-sort, its rank.
Props
- table*
DataTableInstance<T>The TanStack table whose pagination state to show and change. With an unknown page count it shows previous and next only.
Props
- mode*
DataTableSelectAllpageshows the page count and the select-all link;allshows the total and the clear link.- pageCount*
numberHow many rows of the page are selected.- totalCount*
numberHow many rows there are in all, across pages.- labels
Partial<DataTableSelectAllLabels>Overrides for the texts,{ page(count), all(total), selected(total), clear }.
Emits
- selectAll
[]The select-all link was pressed.- clear
[]The clear link was pressed.
Props
- row*
DataTableRow<T>The TanStack row. A checkbox that toggles it, selects a range with Shift, and is disabled when the row cannot be selected.
Props
- row*
DataTableRow<T>The TanStack row. A chevron button that toggles it when it can expand, indented by the row's depth.
Props
- row*
DataTableRow<T>The grouped TanStack row. A chevron button that toggles the group, the value and the number of leaf rows.
Slots
- default
{}The group's value, the column's cell by default.
Data attributes
The parts carry the Table slots, table, table-header, table-row, table-head, table-cell, table-footer, table-caption and table-empty, with the same attributes, plus these:
| data-slot | Attributes | Description |
|---|---|---|
| data-table | data-size, data-loading | The root. Carries --table-thead-h, --table-tfoot-h, --table-pinned-top-h and --table-pinned-bottom-h, the measured heights of the sticky parts. |
| table-row-group | data-index, data-state, data-parity, data-expanded | One tbody per row, the virtual item and the measured element; it carries the row's selected state, stripe parity and expanded state, so a detail row is tinted with its row. |
| table-expanded | — | The detail row inside an expanded row's group. |
| table-group | — | A grouped row, in place of table-row. |
| table-pinned-top | — | The sticky row group of the rows pinned to the top. |
| table-pinned-bottom | — | The sticky row group of the rows pinned to the bottom. |
| table-spacer | — | A row group standing in for rows outside the window; hidden from assistive technology. |
| table-filler | — | The column taking the width left over when every column has a size. |
| table-loading | — | The header row holding the progress bar while loading. |
| table-loading-more | data-direction | The row at an edge while more rows load; hidden from assistive technology. |
| table-end-of-data | data-direction | The row at an edge once it has no more rows. |
| table-skeleton | — | The body of skeleton rows while loading with no data. |
| table-error | — | The row holding the error state, in place of the rows. |
| data-table-column-header | data-sorted | The sort button in a header. |
| data-table-select-header | — | The header checkbox. |
| data-table-select-cell | — | A row's checkbox. |
| data-table-select-all-banner | data-mode | The banner under the toolbar while a page or every row is selected. |
| data-table-expand-cell | — | A row's chevron. |
| data-table-group-cell | — | A grouped row's toggle, value and count. |
| data-table-pagination | — | The bar under the table. |
Accessibility
Screen readers hear "row 5001 of 10001" even when only a handful of rows exist in the DOM: the table has aria-rowcount, and every row has aria-rowindex.
- A focused row stays mounted when it scrolls out of view, so focus isn't lost.
- Focused rows never hide under the sticky header or pinned rows.
- Checkboxes and chevrons are labelled buttons, and the select-all banner is announced.
- Spacers and loading rows are hidden from screen readers.
- The default error message is an alert, so it is read out when it appears.