Data table API
Props, slots, labels and styling of the slotsmith Data table.
Slots
DataTable has 24 slots. Pass a replacement for any of them in components; every slot you leave out keeps its fallback. Element slots receive DOM props, so a library's own element fits as it is; widget slots receive named props and usually need a few lines of adapter.
| Name | Kind | Props it receives | Default fallback | data-* attributes |
|---|---|---|---|---|
Root | <element> | DOM props: | Fallback source |
|
Table | <element> | DOM props: | Fallback source |
|
Head | <element> | DOM props: | Fallback source | — |
Body | <element> | DOM props: | Fallback source |
|
HeaderRow | <element> | DOM props: | Fallback source |
|
HeaderCell | <element> | DOM props: | Fallback source |
|
Foot | <element> | DOM props: | Fallback source | — |
FooterRow | <element> | DOM props: | Fallback source |
|
FooterCell | <element> | DOM props: | Fallback source |
|
Row | <element> | DOM props: | Fallback source |
|
Cell | <element> | DOM props: | Fallback source |
|
Checkbox | {widget} |
| Fallback source | — |
SortTrigger | {widget} |
| Fallback source | — |
SortIcon | {widget} |
| Fallback source | — |
ExpandToggle | {widget} |
| Fallback source |
|
Skeleton | {widget} |
| Fallback source | — |
Empty | {widget} |
| Fallback source | — |
Error | {widget} |
| Fallback source | — |
Pagination | {widget} |
| Fallback source | — |
PaginationButton | {widget} |
| Fallback source | — |
PageSizeSelect | {widget} |
| Fallback source | — |
DragHandle | <element> | DOM props:
| Fallback source |
|
CellEditor | {widget} | No props of its own. | Fallback source | — |
FillHandle | <element> | DOM props:
| Fallback source |
|
Props
Every prop of DataTable, grouped as in the library's documentation. Controlled state comes in pairs: pass a value with its change handler, or only the default to leave the state inside the component.
| Name | Type | Default | Description |
|---|---|---|---|
| Data | |||
data | T | — | The rows to display. For manual pagination, just the current page. Pass this or |
value | T | — | The rows, for a table people edit: the same as |
columnsrequired | DataTableColumnDef< | — | The column definitions. |
get | ( |
| Stable row identity. Defaults to |
| Sorting | |||
sorting | SortingState | — | Controlled sorting state. |
on | ( | — | Called with the new sorting state. |
default | SortingState | [] | Initial sorting when uncontrolled. Defaults to |
manual | boolean | false | The data arrives already sorted (server-side sorting). Defaults to |
enable | boolean | false | Allow sorting by several columns with shift-click. Defaults to |
| Pagination | |||
pagination | PaginationState | — | Controlled pagination state. |
on | ( | — | Called with the new pagination state. |
default | PaginationState | { | Initial pagination when uncontrolled. Defaults to |
manual | boolean | false | The data is already one page (server-side pagination); pass |
row | number | — | Total rows across all pages, for manual pagination. |
page | number | DEFAULT_ | The page sizes offered. Defaults to DEFAULT_PAGE_SIZE_OPTIONS. |
enable | boolean | true |
|
hide | boolean | — | Hide the pagination UI while still paginating. |
| Selection | |||
enable | boolean | | — | Shows a checkbox column. A function decides per row whether it can be selected. |
selection | T | — | Controlled selection, as row objects. Matched to rows by |
on | ( | — | Called with the selected rows, including rows on other server pages. |
default | T | [] | Initial selection when uncontrolled. Defaults to |
reset | boolean | false | Clear the selection whenever the page or page size changes. Defaults to |
| Tree rows | |||
get | ( | — | Returns a row's children, turning the table into a tree. |
set | ( | — | Writes new children into a copy of a tree row and returns it: how the table builds the new tree after a move across parents ( |
get | ( | — | Decides whether a row can expand, e.g. to lazy-load children. |
expanded | ExpandedState | — | Controlled expansion: |
on | ( | — | Called with the new expansion state. |
default | ExpandedState | { | Initial expansion when uncontrolled. Defaults to |
paginate | boolean | false | Count sub-rows towards the page size. Defaults to |
| Row reordering | |||
enable | boolean | false | Lets rows be dragged into a new order, by pointer, touch or keyboard. In a tree table ( |
on | ( | — | Called when a row is dropped in a new place. The table does not reorder itself: store |
reorder | boolean | true | Adds a leading column with each row's drag handle. |
reorder | ReorderWhileSorted | "clearSort" | What a drop means while a column sort is active. |
reorder | boolean | false | In a tree table, rows may be dragged to another parent and another depth, not only among their siblings: drag sideways (or press the left and right arrow keys while a row is lifted) to move it in or out a level. Needs |
can | ( | — | Whether a dragged row may land at a place; places it may not are skipped while dragging. |
reorder | string | — | Tables with the same |
reorder | string | a generated id | This table's name in transfers between the tables of a reorder group. Defaults to a generated id. |
on | ( | — | Called on both tables when rows move between them: |
| Spreadsheet | |||
spreadsheet | boolean | | false | Spreadsheet mode: cells are selected, navigated and edited with the keyboard and the pointer, copied and pasted as tab-separated text, filled with the fill handle and undone. Columns opt in to editing with |
on | ( | — | Called with the new rows after every edit in spreadsheet mode: typing, paste, cut, Delete, fill, undo and redo. The table never changes the rows itself, so store |
| Status | |||
loading | boolean | false | Shows skeleton rows. Defaults to |
error | unknown | — | Any non-nullish value shows the error state. |
on | ( | — | Shows a retry button in the error state. |
| Rendering | |||
components | Partial< | — | Replace any UI slot; the rest fall back to |
labels | Partial< | — | Override any text, e.g. to translate the table. Wins over |
locale | LocaleInput | the provider's | The language: a locale object, or the tag of one given to |
slot | DataTableSlotProps< | — | Extra DOM props for element slots, e.g. per-row classNames. |
on | DataTableContextValue< | — | Called when a body row is clicked (not its checkbox or expand toggle). |
size | "sm" | | — | Density; sets |
striped | boolean | — | Alternate row backgrounds; sets |
table | Partial< | — | Escape hatch: extra options passed straight to TanStack's |
virtual | DataTableVirtualOptions | — | Renders only the rows in view, for long lists: pass the virtualizer hook ( |
Any other prop is passed to the root <div> element.
Labels & locales
Every string DataTable shows or announces, with its English default. Pass labels to change some of them for one component, or locale to switch every string to another language. The demo below does both.
| Key | Type | English default | Description |
|---|---|---|---|
empty | ReactNode | "No data found" | Empty state message. Default: "No data found". |
error | ReactNode | "Something went wrong while loading the data. | Error state message. |
retry | ReactNode | "Retry" | Retry button text. Default: "Retry". |
rows | ReactNode | "Rows per page" | Page-size select label. Default: "Rows per page". |
page | ( | pageInfo(prints | Page info. Default: |
pagination | string | "Pagination" | Accessible name of the pagination landmark. |
previous | string | "Previous page" | Accessible name of the previous-page button. |
next | string | "Next page" | Accessible name of the next-page button. |
select | string | "Select all rows on this page" | Accessible name of the select-all checkbox. |
select | string | "Select row" | Accessible name of each row checkbox. |
expand | string | "Expand row" | Accessible name of the expand toggle on a collapsed row. |
collapse | string | "Collapse row" | Accessible name of the expand toggle on an expanded row. |
reorder | string | "Reorder row" | Accessible name of each row's drag handle. Default: "Reorder row". |
reorder | string | "Press space to lift the row, | How to move a row with the keyboard, given to assistive technology with the drag handle. |
reorder | ( | reorderLifted(prints | Announced when a row is lifted. Default: |
reorder | ( | reorderMoved(prints | Announced on each keyboard step. Default: |
reorder | ( | reorderDropped(prints | Announced when a row is dropped. Default: |
reorder | string | "Reordering cancelled. | Announced when a move is cancelled. Default: "Reordering cancelled." |
reorder | ( | reorderLevel(prints | Announced after a step or a drop that moves a row across parents, with its depth from 1. Default: |
edit | ( | editCell(prints | Spreadsheet mode: the cell editor's accessible name. Default: |
invalid | string | "Enter a number. | Spreadsheet mode: a number cell got text that is not a number. Default: "Enter a number." |
invalid | string | "Choose one of the options. | Spreadsheet mode: a select cell got text that matches no option. Default: "Choose one of the options." |
invalid | string | "Enter a valid date. | Spreadsheet mode: a date cell got text that is not a date. Default: "Enter a valid date." |
invalid | string | "Enter TRUE or FALSE. | Spreadsheet mode: a checkbox cell got text that is neither true nor false. Default: "Enter TRUE or FALSE." |
cells | ( | cellsCopied(prints | Spreadsheet mode: announced after a copy. Default: |
cells | ( | cellsCut(prints | Spreadsheet mode: announced after a cut. Default: |
cells | ( | cellsPasted(prints | Spreadsheet mode: announced after a paste; |
cells | ( | cellsCleared(prints | Spreadsheet mode: announced after Delete. Default: |
cells | ( | cellsFilled(prints | Spreadsheet mode: announced after a fill. Default: |
undone | string | "Undone. | Spreadsheet mode: announced after an undo. Default: "Undone." |
redone | string | "Redone. | Spreadsheet mode: announced after a redo. Default: "Redone." |
| Der Process | Franz Kafka | 1925 |
| Effi Briest | Theodor Fontane | 1896 |
| Der Steppenwolf | Hermann Hesse | 1927 |
import { DataTable, type DataTableColumnDef } from "slotsmith/data-table";
import { de } from "slotsmith/locales/de";
type Book = { id: string; title: string; author: string; year: number };
const books: Book[] = [
{ id: "1", title: "Der Process", author: "Franz Kafka", year: 1925 },
{ id: "2", title: "Effi Briest", author: "Theodor Fontane", year: 1896 },
{ id: "3", title: "Der Steppenwolf", author: "Hermann Hesse", year: 1927 },
{ id: "4", title: "Buddenbrooks", author: "Thomas Mann", year: 1901 },
{ id: "5", title: "Momo", author: "Michael Ende", year: 1973 },
];
const columns: DataTableColumnDef<Book>[] = [
{ accessorKey: "title", header: "Titel" },
{ accessorKey: "author", header: "Autor" },
{ accessorKey: "year", header: "Jahr" },
];
export default function Labels() {
return (
<DataTable
data={books}
columns={columns}
// Every string in German, from the ready-made pack…
locale={de}
// …except the page counter, replaced for this table only.
labels={{ pageInfo: (page, pageCount) => `${page} / ${pageCount}` }}
defaultPagination={{ pageIndex: 0, pageSize: 3 }}
pageSizeOptions={[3, 5]}
/>
);
}The ready-made language packs, right-to-left support and app-wide locales are on the Languages page.
Styling
The class names the fallbacks of DataTable put on their elements, and the tokens its stylesheet reads. Set a token on the component, or on any element around it, to restyle it; target a class only for what no token covers.
| Class | Slot |
|---|---|
.sdt | |
.sdt__scroll | — |
.sdt__table | |
.sdt__head | |
.sdt__body | |
.sdt__foot | |
.sdt__row | |
.sdt__cell | |
.sdt__cell--drag | — |
.sdt__cell--select | — |
.sdt__checkbox | |
.sdt__sort | |
.sdt__sort-icon | |
.sdt__tree | — |
.sdt__tree-spacer | — |
.sdt__expand | |
.sdt__skeleton | |
.sdt__message | |
.sdt__error | |
.sdt__button | — |
.sdt__button--icon | |
.sdt__pagination | |
.sdt__pagination-buttons | — |
.sdt__pagination-info | — |
.sdt__page-size | |
.sdt__page-size-select | — |
.sdt__drag | |
.sdt__editor-host | — |
.sdt__cell-ghost | — |
.sdt__checkbox-cell | — |
.sdt__editor | |
.sdt__editor-input | — |
.sdt__editor-control | — |
.sdt__editor-trigger | — |
.sdt__editor-error | — |
.sdt__fill-handle | |
.sdt__sr-only | — |
| Token | Layer |
|---|---|
--sdt-accent | This component |
--sdt-bg | This component |
--sdt-border | This component |
--sdt-checkbox-size | This component |
--sdt-danger | This component |
--sdt-font-size | This component |
--sdt-header-bg | This component |
--sdt-hover | This component |
--sdt-max-height | This component |
--sdt-muted | This component |
--sdt-padding-x | This component |
--sdt-padding-y | This component |
--sdt-radius | This component |
--sdt-selected | This component |
--sdt-skeleton-bg | This component |
--sdt-skeleton-bg-2 | This component |
--sdt-stripe | This component |
--sdt-surface | This component |
--sdt-text | This component |
--ss-accent | Shared by every component |
--ss-border | Shared by every component |
--ss-danger | Shared by every component |
--ss-font-size | Shared by every component |
--ss-hover | Shared by every component |
--ss-muted | Shared by every component |
--ss-radius | Shared by every component |
--ss-selected | Shared by every component |
--ss-surface | Shared by every component |
--ss-text | Shared by every component |
Every token switches to its dark value under .dark, [data-theme="dark"], on the page or on any element around the component.