Table
Table is the catalog's first TanStack-backed component: its state engine is
@tanstack/react-table, not a Spar primitive
(Spar intentionally has no table). The public API is props-first — a common
table is a single <Table data columns getRowId /> call — with a column-def +
slot escape hatch for customization. getRowId is mandatory: it is the single
identity source row selection keys on.
Playground
A single <Table> call with sortable headers, a Badge cell, a checkbox column
filter, multi-row selection, striping, and client pagination.
Basic
The minimum is data, columns, and getRowId. accessor is a property key,
a dot-path ('user.city'), or a (row) => value function.
Custom cells & actions
A column's cell is a React render-prop (never an HTML string) — put a
Badge, Button, icon, or anything else inside. Table still owns the <td>
container (padding, alignment, sticky, a11y); cell only supplies the content.
Column filtering
A column's filter is two-tier: declarative presets for the common cases,
and a render escape hatch for everything else. Either way Table owns the
plumbing — the header trigger, the Popover (a real portal), the active-state
dot, and the value wiring to TanStack.
Presets
For the common controls, pass a preset — a bare string for text, or an object
with type (+ options for the choice controls):
type | Control | Filter value | Match |
|---|---|---|---|
text | Input | string | substring |
select | Select (single) | string | equality |
radio | Radio list | string | equality |
checkbox | Checkbox list | string[] | membership |
multi-select | Checkbox list¹ | string[] | membership |
{ id: 'name', header: 'Name', accessor: 'name', filter: 'text' }
{ id: 'role', header: 'Role', accessor: 'role',
filter: { type: 'checkbox', options: [
{ label: 'Admin', value: 'admin' },
{ label: 'User', value: 'user' },
] } }
¹ Spar's Select has no multi mode yet, so multi-select currently renders
the same Checkbox list as checkbox. The checkbox and multi-select
options sit in a named group, exposed as the filterOptions slot (it reuses
the panel body's tk-table-filter-panel-body stacking class), so
classNames.filterOptions / slotProps.filterOptions or a theme can restyle
the list.
While a filter is active its panel shows a Clear button. Its text comes from
labels.filterClear (see Labels), for presets and custom render
panels alike.
Custom filters (escape hatch)
When no preset fits — a number range, a date range, a combobox, async-loaded
options — pass render instead. It receives
{ value, setValue, clear, column, close, fieldLabel } and returns any control;
Table still owns the surrounding popover. value is whatever shape your control
writes, so pair it with a filterFn (client mode) and, if the default non-empty
heuristic is wrong, an isActive predicate for the active dot.
Why both tiers?
The legacy takeoff-ui filter was a closed type enum, which could never
cover every column's needs, so customization ended up blocked on a library
change. Every mature table (Mantine/Material React Table, AG Grid, MUI X)
instead layers a short preset under a render escape hatch. Presets keep
the 90% case one-line; render (the same inversion as cell /
expansion.render) leaves the rest fully open.
Expandable rows
Expansion has two mutually exclusive shapes. The first is a detail
panel: pass expansion.render to render a disclosure row beneath each row.
The second is tree data (getSubRows), covered below — supplying both keeps
tree mode and suppresses the detail panel.
Tree data (sub-rows)
For hierarchical data, pass getSubRows to read each row's children and an
expansion config (without render) to make the expand toggle reveal those
flattened sub-rows instead of a detail panel. The toggle appears only on rows
that actually have children; row.depth is available inside a cell to indent
nested rows. Here expansion={{ defaultValue: true }} expands everything on
mount.
Sticky columns & header
Pin columns to the left or right edge with sticky: 'left' | 'right' on a
column def. Add stickyHeader to also pin the header row during vertical
scroll. Pass maxHeight to the viewport via slotProps.tableViewport to enable
vertical scroll — sticky header only activates when the viewport itself scrolls,
not a parent container. The example below constrains the wrapper to 720px wide
and the viewport to 280px tall so both axes scroll.
Column resizing
Pass columnResizing to let users resize columns by dragging a header edge, or
with ← / → on a focused handle. true keeps the widths
uncontrolled; an object takes value / defaultValue / onChange over a
{ [columnId]: px } map. onChange fires once per resize, not on every pointer
move, so you can persist it directly: the demo saves to localStorage, so the
widths survive a reload.
Per column, resizable: false removes the handle and minWidth (default 50px)
/ maxWidth bound it. A double-click returns a column to its declared width,
or fits it to its content. Once a table is resized, cells stay on one line and
long text ends in an ellipsis.
mode decides where a growing column gets its room:
'fit'(default): the table stays as wide as its container. The last unpinned column without a declaredwidthhas no handle and takes up the slack; a growing column takes room from it and the columns in between, keeping their text readable for as long as it can.'expand': every column keeps its width, and the table grows past its container and scrolls.
If you switch mode at runtime, reset the stored widths too.
Density
size scales the cell padding — 'xsmall', 'small', or 'base' (the
default) — and surfaces as data-size for recipes to scope against.
Empty state
When data is empty, Table renders a single full-width cell. The default copy
is No data (labels.noData); pass emptyState to supply your own node, or
emptyState={null} to leave the cell blank. While loading is true the empty
copy is suppressed so it does not flash mid-fetch.
Loading
loading overlays a Spar Spinner (role="status"), marks the table
aria-busy, and sets data-loading for theming. Existing rows stay visible
beneath the overlay so the table does not collapse during a refetch.
Server (manual) data
In manual mode Table processes nothing in-memory. It maps to TanStack's
manualSorting / manualFiltering / manualPagination and emits one bundled
onDataRequest derived from the current sorting, filters, and pagination —
fetch the page yourself and feed the result back through data. pagination
must carry rowCount so the page count and Next/Last controls can be computed.
<Table
data={page.rows}
columns={columns}
getRowId={row => row.id}
manual
sorting={{ value: sorting, onChange: setSorting }}
filtering={{ value: filters, onChange: setFilters }}
pagination={{
pageSize,
pageIndex,
rowCount: page.total,
onChange: setPagination,
}}
onDataRequest={({ pagination, sorting, filters }) =>
fetchPage({ pagination, sorting, filters })
}
loading={isFetching}
/>
Exporting data
Table ships no export engine — it exposes the current filtered + sorted rows
as a plain value projection via getExportRows(tableRef.current). Formatting
and file download (CSV / Excel / PDF) stay on your side, keeping those heavy
dependencies out of the bundle.
import { Table, getExportRows } from '@takeoff-ui/react-spar';
const tableRef = useRef(null);
<Table
data={rows}
columns={columns}
getRowId={r => r.id}
tableRef={tableRef}
/>;
// later — e.g. a "Download CSV" button:
const rowsToExport = getExportRows(tableRef.current); // Array<Record<columnId, value>>
Labels
Every string Table renders — visible text and accessible names — comes from the
labels prop, whether you are translating it or just rewording it. Pass only
the keys you need; the rest keep their English defaults, and an empty or
whitespace-only string also falls back to the default. Dynamic entries are
templates whose {placeholders} Table fills in, so word order stays with the
translation and the object can live in a JSON translation file.
<Table
data={rows}
columns={columns}
labels={{
noData: 'Veri yok',
filterClear: 'Temizle',
filterButton: '{column} sütununu filtrele',
filterValue: '{column} filtre değeri',
filterSelectPlaceholder: 'Seçiniz',
pageStatus: 'Sayfa {page} / {pageCount}',
itemsRange: '{total} kayıttan {start}-{end}',
pageButton: '{page}. sayfaya git',
}}
/>
To localize every Table in the app at once, set it as provider defaultProps.
An instance labels is merged over it key by key, so a single table can
override one string and keep the rest.
<TakeoffSparProvider
components={{ Table: { defaultProps: { labels: trTableLabels } } }}
>
<App />
</TakeoffSparProvider>
The filter-trigger, pagination and expand-button names come from labels: an
aria-label in slotProps.filterButton / slotProps.pagination /
slotProps.expandButton is ignored. On the filter trigger and the checkbox
filter group (filterOptions) an aria-labelledby is dropped too, so labels
always names them. filterValue names the text filter input (a
filter.placeholder stays a visible hint), the radio and checkbox groups, and
the select trigger together with its visible value. {column} in filterButton
/ filterValue is the column's filter.label, else its header text, else its
id (for an empty, node or function header, so set filter.label there). Do
not confuse the two: filter.label names one column, while the root labels
prop holds the strings Table itself renders. Template numbers are inserted as-is
(1234, not 1.234), and templates have no plural rules.
| Key | Default | Used for |
|---|---|---|
noData | 'No data' | Empty table (any emptyState wins, provider too) |
loading | Spinner's own ('Loading') | Loading spinner's accessible name |
filterButton | 'Filter {column}' | Filter trigger's name ({column}) |
filterValue | 'Filter {column} value' | Filter field / group name ({column}) |
filterClear | 'Clear' | Filter panel Clear button |
filterSelectPlaceholder | 'Select' | select filter trigger (filter.placeholder wins) |
paginationLandmark | 'Pagination' | Pagination nav landmark's name |
pageStatus | 'Page {page} of {pageCount}' | Page indicator |
pageStatusUnknown | 'Page {page}' | Page indicator while the page count is 0 |
itemsRange | 'Items {start}-{end} of {total}' | Item range |
noItems | '0 items' | Item range with no rows ({total}, always 0) |
firstPage / previousPage / nextPage / lastPage | 'First page' … | Pagination buttons |
pageButton | 'Go to page {page}' | Page-number buttons |
currentPageButton | 'Page {page}, current page' | Current page's button |
rowsPerPage | 'Rows per page' | Page-size select |
pageJumpInput | 'Go to page' | Page-jump input |
pageJumpSubmit | 'Go' | Page-jump submit (translate with pageJumpInput) |
selectAllRows / selectRow | 'Select all rows' / 'Select row' | Selection controls |
rowSelection | 'Row selection' | Hidden header of the single-selection column |
expandRow / collapseRow | 'Expand row' / 'Collapse row' | Expand button |
rowDetails | 'Row details' | Hidden header of the expansion column |
resizeHandle | 'Resize {column} column' | Column resize handle's name ({column}) |
Accessibility
- Renders a native
<table>/<thead>/<tbody>/<th scope="col">/<td>, so screen-reader table navigation, header association, and row/column counts come for free. - Sortable headers are real
<button>s (Enter / Space toggle sorting) and the<th>carriesaria-sort(ascending|descending|none). - Row selection composes Spar
Checkbox(multiple) orRadio(single) with accessible names; the select-all header checkbox is multiple-mode only. - Pagination is a labelled
navigationregion; the page-size control is a SparSelectwith an accessible name, and the nav buttons carryaria-labels. - The loading overlay surfaces the Spar
Spinner(role="status") and the table is markedaria-busywhileloading. - Column resize handles follow the window-splitter pattern: a focusable
role="separator"witharia-orientation="vertical", alabels.resizeHandlename (Resize <header> column), andaria-valuenow/aria-valuemin/aria-valuemaxin px.
| Key | Behavior |
|---|---|
| Tab | Move between interactive controls in the table. |
| Enter / Space | Toggle sorting on a focused sortable header. |
| ← / → | Narrow / widen the column of a focused resize handle by 10px (50px with Shift). |
API Reference
Table
See TanStack Table docs for primitive behavior.
Props
| Name | Type | Default | Description |
|---|---|---|---|
| data | TData[] | - | Row data. In manual mode this is the current server page. |
| columns | TableColumnDef<TData>[] | - | Column definitions. See TableColumnDef. |
| getRowId | (row: TData, index: number) => string | - | Stable row identity (single source of truth). |
| size | TableSize | 'base' | Density scale. |
| striped | boolean | false | Zebra-stripe rows → data-striped. |
| bordered | boolean | false | Cell borders → data-bordered. |
| stickyHeader | boolean | false | Pin the header row during vertical scroll → data-sticky-header. |
| manual | boolean | false | Server mode. When true, Table processes nothing in-memory — it maps to TanStack's manualSorting/manualFiltering/manualPagination and emits a single bundled onDataRequest (RFC §3.3). |
| selection | TableSelectionConfig | - | Row selection (single/multiple + select-all). Composes Spar Checkbox/Radio. |
| sorting | TableSortingConfig | - | Sorting (multi-sort opt-in). |
| filtering | TableFilteringConfig | - | Column filtering. Filter UIs render in a Spar Popover. |
| expansion | TableExpansionConfig<TData> | - | Expandable rows with a render-prop body. |
| pagination | boolean | TablePaginationConfig | - | Pagination. true enables it with defaults; an object configures it. |
| columnResizing | boolean | TableColumnResizingConfig | - | User-resizable columns: a handle on each resizable header edge (drag or Left/Right arrows). true keeps the widths uncontrolled; an object adds value / defaultValue / onChange and mode. |
| loading | boolean | false | Loading state → data-loading + a loading overlay. |
| emptyState | React.ReactNode | - | Content rendered when there are no rows. Defaults to labels.noData; pass null (or false) to leave the empty cell blank. |
| labels | Partial<TableLabels> | - | Every user-facing string Table renders — visible text and accessible names — to translate or reword. Pass only the keys you need; the rest keep their English defaults, and an empty or whitespace-only string also falls back to the default. Set it app-wide through TakeoffSparProvider components.Table.defaultProps.labels; an instance labels is merged over it key by key. emptyState still wins over labels.noData, even when it comes from the provider's defaultProps, while an aria-label in slotProps.filterButton / slotProps.pagination / slotProps.expandButton is ignored in favour of labels (on filterButton and filterOptions an aria-labelledby is dropped too). See TableLabels. |
| getSubRows | (row: TData) => TData[] | - | Sub-row reader for tree data (feeds TanStack getSubRows). Pair it with expansion (sans render) so expanding a row reveals its flattened sub-rows. When getSubRows is omitted, expansion falls back to the detail-panel mode driven by expansion.render. Supplying both keeps tree mode and suppresses the detail panel. |
| tableRef | Ref<TanStackTable<TData> | null> | - | Escape hatch for the rare imperative need — receives the TanStack table instance (RFC §2.3: controlled props + an optional instance ref, never an imperative @Method surface). Also the access point for getExportRows(). |
| classNames | Partial<Record<TableSlot, string>> | - | Per-slot class name overrides. |
| slotProps | Partial<Record<TableSlot, React.HTMLAttributes<HTMLElement>>> | - | Per-slot HTML attribute overrides. An aria-label here is ignored for filterButton, pagination, expandButton and filterOptions, whose names come from labels; on filterButton and filterOptions an aria-labelledby (and the group's role) is dropped too. |
| className | string | - | Appends custom classes to the root container. |
Events
| Name | Type | Default | Description |
|---|---|---|---|
| onDataRequest | (request: TableDataRequest) => void | - | Bundled server data-request callback (manual mode). See TableDataRequest. |
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for the root container. |
| data-slot="table-viewport" | Always | The table-only horizontal/vertical scroll container; pagination remains outside it. |
| data-size | Always | Reflects the resolved size (density) so recipes can scope cell padding. |
| data-striped | When striped is true. | Enables zebra striping on body rows. |
| data-bordered | When bordered is true. | Adds vertical separators between columns. |
| data-sticky-header | When stickyHeader is true. | Pins the header row during vertical scroll. |
| data-scrolled | On the table viewport while scrollTop > 0. | Adds sticky-header elevation only after vertical scrolling begins. |
| data-loading | When loading is true. | Shows the loading overlay; the table is also marked aria-busy. |
| data-align | On every header/body cell with an align (or column meta.headerAlign). | Drives cell text-align (start | center | end). |
| data-sticky | On cells of a column with sticky: "left" | "right". | Pins the column; per-edge offset + z-index are applied inline. |
| aria-sort | On sortable header cells. | A11y sort state (ascending | descending | none); the sort arrow mirrors it via data-direction. |
| data-fixed-layout | With columnResizing, once any column has a user width. | Switches the table to table-layout: fixed. |
| data-resize-mode | With columnResizing: fit (default) or expand. | In expand mode the bordered viewport hugs the table. |
| data-resizing | On the column resize handle while it is being dragged. | Highlights the active handle; the root keeps the col-resize cursor while any handle carries it. |
| data-selected | On a selected body row. | Theme hook for the selected-row background. |
Type Definitions
| Name | Definition |
|---|---|
| TableSize | 'xsmall' | 'small' | 'base' |
| TableSelectionConfig | { mode: 'single' | 'multiple' } |
| TableSortingConfig | { multi?: boolean } |
| TableFilteringConfig | { value?: T; defaultValue?: T; onChange?: (value: T) => void } |
| TablePaginationConfig | { pageSize?: number; pageIndex?: number; pageSizeOptions?: number[]; rowCount?: number; onChange?: (pagination: PaginationState) => void } |
| TableColumnResizingConfig | { mode?: TableColumnResizingMode } |
| TableLabels | { noData: string; loading?: string; filterButton: string; filterValue: string; filterClear: string; filterSelectPlaceholder: string; paginationLandmark: string; pageStatus: string; pageStatusUnknown: string; itemsRange: string; noItems: string; firstPage: string; previousPage: string; nextPage: string; lastPage: string; pageButton: string; currentPageButton: string; rowsPerPage: string; pageJumpInput: string; pageJumpSubmit: string; selectAllRows: string; selectRow: string; rowSelection: string; expandRow: string; collapseRow: string; rowDetails: string; resizeHandle: string } |
| TableSlot | | 'root' | 'tableViewport' | 'table' | 'header' | 'headerRow' | 'headerCell' | 'headerContent' | 'headerLabel' | 'sortTrigger' | 'sortIcon' | 'resizeHandle' | 'body' | 'row' | 'cell' | 'selectionCell' | 'expandCell' | 'expandButton' | 'expandedRow' | 'filterButton' | 'filterPanel' | 'filterOptions' | 'pagination' | 'paginationInfo' | 'paginationNav' | 'paginationActions' | 'paginationSize' | 'paginationGoToPage' | 'empty' | 'loading' |
| TableDataRequest | { pagination: PaginationState; sorting: SortingState; filters: ColumnFiltersState } |