Table Set
Customers
| Ada | London | 12 |
| Alan | Manchester | 21 |
| Edsger | Rotterdam | 17 |
The composed table shell around Table: a title, a column-visibility dropdown, a table ↔ cards view switcher, client-side pagination (or infinite scroll), and optional tabs that switch between distinct views (each with its own columns + rows).
Import
Section titled “Import”<script> import TableSet from "@invisible-ui/svelte/TableSet.svelte";</script><script setup> import { TableSet } from "@invisible-ui/vue";</script>import { TableSet } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-table-set></ds-table-set>In Elements, assign data through properties and listen for the bubbling
events. Each callback becomes an event with the same name in kebab case, and
the no-results “Clear filters” action appears with filters-clearable:
<ds-table-set heading="Customers" page-size="10" configurable allow-view-toggle> <ds-search-field slot="toolbar" label="Filter customers" hide-label></ds-search-field></ds-table-set>
<script type="module"> import "@invisible-ui/elements/define";
const set = document.querySelector("ds-table-set"); set.columns = [ { key: "name", header: "Name", sortable: true, hideable: false }, { key: "city", header: "City" }, ]; set.rows = customers; set.addEventListener("page-change", ({ detail }) => console.log(detail.page));</script>For a single table, give <ds-table-set> one view. The element it renders
each view with is internal, as in the other adapters.
Props (selected)
Section titled “Props (selected)”| Prop | Type | Default | Description |
|---|---|---|---|
columns | TableColumnDef[] | [] | Single-view columns (used when views is not provided). |
rows | TableRow[] | [] | Single-view rows (used when views is not provided). |
views | TableViewDef[] | undefined | undefined | Tabs, each { id, label, columns, rows }. |
activeView | string | undefined | undefined | The active view id (controlled). Defaults to the first view. |
viewsLabel | string | undefined | undefined | Accessible name for the views tab list. |
onViewChange | ((id: string) => void) | undefined | undefined | Called when the active view changes. |
title | string | undefined | undefined | Header title. |
titleLevel | 2 | 3 | 4 | 5 | 6 | 2 | |
caption | string | undefined | undefined | Accessible name for the table/list (a <caption> in table view). |
hideCaption | boolean | false | |
pageSize | number | undefined | undefined | Rows per page (client-side pagination). |
page | number | 1 | |
paginationLabel | string | undefined | undefined | Accessible name for the pagination nav. Defaults to the i18n catalog's "Table pages". |
onPageChange | ((page: number) => void) | undefined | undefined | |
infinite | boolean | false | Infinite-scroll mode instead of pagination. |
hasMore | boolean | false | Infinite-scroll mode instead of pagination. |
loading | boolean | false | |
onLoadMore | (() => void) | undefined | undefined | Infinite-scroll mode instead of pagination. |
loadMoreLabel | string | undefined | undefined | Load-more button text. Defaults to the i18n catalog's "Load more". |
loadingLabel | string | undefined | undefined | Loading status text. Defaults to the i18n catalog's "Loading…". |
sort | SortState | null | null | |
onSortChange | ((sort: SortState | null) => void) | undefined | undefined | |
hiddenColumns | string[] | [] | |
onHiddenColumnsChange | ((hidden: string[]) => void) | undefined | undefined | |
view | "table" | "card" | "table" | |
allowViewToggle | boolean | false | Table ↔ cards segmented control. |
configurable | boolean | false | Column-visibility dropdown (Popover + checkboxes). |
configLabel | string | undefined | undefined | Column-visibility dropdown label. Defaults to the i18n catalog's "Columns". |
cardTitleKey | string | undefined | undefined | Map columns to the card title/description. |
cardDescriptionKey | string | undefined | undefined | Map columns to the card title/description. |
getValue | (row: TableRow, key: string) => unknown | (row, key) => row[key] | |
getRowId | (row: TableRow, index: number) => string | number | defaultGetRowId | |
selectionMode | SelectionMode | "none" | Row selection: off by default. single or multiple adds the column. |
selectedRowIds | RowId[] | [] | The selected row ids (controlled). Replace the array; do not mutate it. |
onSelectedRowIdsChange | ((ids: RowId[]) => void) | undefined | undefined | Called with the next ids after a user selection action. |
isRowSelectable | (row: TableRow) => boolean | () => true | Marks rows the user may select. Others render without a checkbox. |
getRowLabel | ((row: TableRow) => string) | undefined | undefined | Names a row for its selection checkbox ("Select {name}"). Optional in the type, but required at runtime whenever selection is active. |
filtersActive | boolean | false | Whether the consumer's filters are active. Filtering itself stays outside. |
totalRowCount | number | undefined | undefined | Total unfiltered row count when known; 0 means the dataset is empty. |
filterRevision | string | number | undefined | undefined | Changing this (or filtersActive) resets the local page to one. |
onClearFilters | (() => void) | undefined | undefined | Clears the consumer's filters; enables the built-in no-results action. |
noResultsLabel | string | undefined | undefined | Copy for the no-results state. Defaults to the i18n catalog's message. |
toolbar | Snippet | undefined | undefined | Header content beside the title, e.g. filters or actions. |
cell | Snippet<[{ row: TableRow; column: TableColumnDef; value: unknown; rowIndex: number }]> | undefined | undefined | Custom cell content, in the table and in the cards. Defaults to the cell value. |
A selected subset of props is shown.
| Prop | Type | Default | Description |
|---|---|---|---|
columns | TableColumnDef[] | () => [] | Single-view data (used when views is not provided). |
rows | TableRow[] | () => [] | |
views | TableViewDef[] | undefined | Distinct views shown as tabs; each supplies its own columns and rows. |
activeView | string | undefined | The active view id (controlled). Defaults to the first view. |
viewsLabel | string | undefined | Accessible name for the views tab list. Defaults to the catalog's "Views". |
onViewChange | (id: string) => void | undefined | Called when the active view changes. |
title | string | undefined | Optional title shown in the header (rendered as a heading). |
titleLevel | 2 | 3 | 4 | 5 | 6 | 2 | |
caption | string | undefined | Accessible name for the table/list (a <caption> in table view). |
hideCaption | boolean | false | |
pageSize | number | undefined | |
page | number | 1 | |
paginationLabel | string | undefined | Accessible name for the pagination nav. Defaults to the catalog's "Table pages". |
onPageChange | (page: number) => void | undefined | |
infinite | boolean | false | |
hasMore | boolean | false | |
loading | boolean | false | |
onLoadMore | () => void | undefined | |
loadMoreLabel | string | undefined | Load-more button text. Defaults to the catalog's "Load more". |
loadingLabel | string | undefined | Loading status text. Defaults to the catalog's "Loading…". |
sort | SortState | null | null | |
onSortChange | (sort: SortState | null) => void | undefined | |
hiddenColumns | string[] | () => [] | |
onHiddenColumnsChange | (hidden: string[]) => void | undefined | |
view | "table" | "card" | "table" | |
allowViewToggle | boolean | false | |
configurable | boolean | false | |
configLabel | string | undefined | Column-visibility dropdown label. Defaults to the catalog's "Columns". |
cardTitleKey | string | undefined | |
cardDescriptionKey | string | undefined | |
getValue | (row: TableRow, key: string) => unknown | (row: TableRow, key: string) => row[key] | |
getRowId | (row: TableRow, index: number) => string | number | defaultGetRowId | |
selectionMode | SelectionMode | "none" | Row selection: off by default. single or multiple adds the column. |
selectedRowIds | RowId[] | () => [] | The selected row ids (controlled). Replace the array; do not mutate it. |
onSelectedRowIdsChange | (ids: RowId[]) => void | undefined | Called with the next ids after a user selection action. |
isRowSelectable | (row: TableRow) => boolean | () => true | Marks rows the user may select. Others render without a checkbox. |
getRowLabel | (row: TableRow) => string | undefined | Names a row for its selection checkbox ("Select {name}"). Optional in the type, but required at runtime whenever selection is active. |
filtersActive | boolean | false | Whether the consumer's filters are active. Filtering itself stays outside. |
totalRowCount | number | undefined | Total unfiltered row count when known; 0 means the dataset is empty. |
filterRevision | string | number | undefined | Changing this (or filtersActive) resets the local page to one. |
onClearFilters | () => void | undefined | Clears the consumer's filters; enables the built-in no-results action. |
noResultsLabel | string | undefined | Copy for the no-results state. Defaults to the i18n catalog's message. |
Slots: cell, toolbar.
| Prop | Type | Default | Description |
|---|---|---|---|
columns | TableColumnDef[] | EMPTY | Single-view columns (used when views is not provided). |
rows | TableRow[] | EMPTY | Single-view rows (used when views is not provided). |
views | TableViewDef[] | — | Distinct views shown as tabs; each supplies its own columns and rows. |
activeView | string | — | The active view id. Controllable mirror: selecting a tab updates it locally and reports through onViewChange; a later prop value overwrites the local choice without a callback. Defaults to the first view. |
viewsLabel | string | — | Accessible name for the views tab list. Defaults to the catalog's "Views". |
onViewChange | (id: string) => void | — | Called when the user selects another view. |
title | string | — | Optional title shown in the header (rendered as a heading). |
titleLevel | 2 | 3 | 4 | 5 | 6 | 2 | |
caption | string | — | Accessible name for the table or list (a <caption> in table view). |
toolbar | ReactNode | — | Header content beside the title, such as filters or actions. |
hideCaption | boolean | — | Visually hide the caption (still available to assistive tech). |
pageSize | number | — | Rows per page. Without it, every row shows. |
page | number | — | The current page (controllable mirror). Defaults to 1. |
paginationLabel | string | — | Accessible name for the pagination nav. Defaults to the catalog's "Table pages". |
onPageChange | (page: number) => void | — | Called with the page after a user action, or after the component moved it. |
infinite | boolean | — | Load rows on demand instead of paging them. |
hasMore | boolean | — | Infinite mode: more rows are available. |
loading | boolean | — | Infinite mode: rows are loading. |
onLoadMore | () => void | — | Infinite mode: called when the user, or the end of the list, asks for more. |
loadMoreLabel | string | — | Load-more button text. Defaults to the catalog's "Load more". |
loadingLabel | string | — | Loading status text. Defaults to the catalog's "Loading…". |
sort | SortState | null | — | The active sort (controllable mirror). Defaults to the first sortable column. |
onSortChange | (sort: SortState | null) => void | — | |
hiddenColumns | string[] | — | Hidden column keys (controllable mirror). |
onHiddenColumnsChange | (hidden: string[]) => void | — | |
view | "table" | "card" | — | The body layout (controllable mirror). Defaults to table. |
allowViewToggle | boolean | — | Show the table and cards switch. |
configurable | boolean | — | Show the column-visibility settings. |
configLabel | string | — | Column-visibility settings label. Defaults to the catalog's "Columns". |
cardTitleKey | string | — | Card view: the column shown as each card's title. Defaults to the first column. |
cardDescriptionKey | string | — | Card view: the column shown as each card's description. |
getValue | (row: TableRow, key: string) => unknown | — | |
getRowId | (row: TableRow, index: number) => string | number | — | |
selectionMode | SelectionMode | — | Row selection: off by default. single or multiple adds the column. |
selectedRowIds | RowId[] | — | The selected row ids (controlled). Replace the array; do not mutate it. |
onSelectedRowIdsChange | (ids: RowId[]) => void | — | Called with the next ids after a user selection action. |
isRowSelectable | (row: TableRow) => boolean | — | Marks rows the user may select. Others render without a checkbox. |
getRowLabel | (row: TableRow) => string | — | Names a row for its selection checkbox ("Select {name}"). Optional in the type, but required at runtime whenever selection is active. |
filtersActive | boolean | — | Whether the consumer's filters are active. Filtering itself stays outside. |
totalRowCount | number | — | Total unfiltered row count when known; 0 means the dataset is empty. |
filterRevision | string | number | — | Changing this (or filtersActive) resets the local page to one. |
onClearFilters | () => void | — | Clears the consumer's filters; enables the built-in no-results action. |
noResultsLabel | string | — | Copy for the no-results state. Defaults to the catalog's message. |
renderCell | (context: TableCellContext) => ReactNode | — | Custom cell content, in the table and in the cards. Defaults to the cell value, as text. |
| Attribute | Reactive | Description |
|---|---|---|
active-view | yes | |
views-label | yes | |
heading | yes | |
heading-level | yes | |
caption | yes | |
hide-caption | yes | |
page-size | yes | |
page | yes | |
pagination-label | yes | |
infinite | yes | |
has-more | yes | |
loading | yes | |
load-more-label | yes | |
loading-label | yes | |
view | yes | table|card |
allow-view-toggle | yes | |
configurable | yes | |
config-label | yes | |
card-title-key | yes | |
card-description-key | yes | |
selection-mode | yes | none|single|multiple |
filters-active | yes | |
total-row-count | yes | |
filter-revision | yes | |
filters-clearable | yes | |
no-results-label | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: columns, rows, views, activeView, sort, hiddenColumns, selectedRowIds, getValue, getRowId, isRowSelectable, getRowLabel, renderCell.
Emits: view-change (detail.id) after a tab is selected, plus the active view's sort-change, hidden-columns-change, selected-row-ids-change, page-change, load-more and clear-filters.
Row selection
Section titled “Row selection”Customers with selection
| Ada | London | 12 | |
| Alan | Manchester | 21 | |
| Edsger | Rotterdam | 17 |
Selected: 2
Set selectionMode to single or multiple to add a leading checkbox column.
The selection is controlled: pass selectedRowIds and update it from
onSelectedRowIdsChange. Ids of rows that are on other pages, filtered out, or
no longer selectable are kept as they are; the component never prunes the
selection, and switching selectionMode never clears it.
- Every row needs a stable, unique id:
row.idor a customgetRowId. The index fallback of the defaultgetRowIdis not accepted for selection, and ids must be unique across all rows the component receives (uniqueness across unloaded server pages is the consumer’s responsibility). The controlledselectedRowIdsholds each id once; duplicates are a consumer error. getRowLabelis required while selection is active: it names each row’s checkbox (Select {name}). Empty or whitespace-only labels are invalid.- Misuse throws in development. In production the component degrades deterministically (the row is not selectable, the first duplicate wins, the checkbox falls back to the id as its name), but those fallbacks are outside the supported contract.
- The select-all checkbox addresses only the rendered page’s selectable rows
and is disabled when there are none;
singlemode has no select-all, and re-activating the selected row empties the selection. - With tabs (
views), the forwarded selection is shared across views. For a per-view selection, swapselectedRowIdsfromonViewChange.
Filtering coordination
Section titled “Filtering coordination”Customers with filters
| Ada | London | 12 | |
| Alan | Manchester | 21 | |
| Barbara | Boston | 9 |
Selected: none
Filtering itself stays in the application: predicates, schemas, query state
and requests never enter the component. Your filter controls live in the
toolbar snippet (a slot="toolbar" child in Elements); the set receives the
already-filtered rows plus a few coordination inputs.
filtersActivesays whether any filter is applied. With zero rows it separates two states:totalRowCountof0is an empty dataset (the ordinary empty table), anything else is no results (an Empty State with thenoResultsLabelcopy and, whenonClearFiltersis given, a “Clear filters” action).- Changing
filtersActiveor the explicitfilterRevisionresets the local page to one and reports it throughonPageChangeexactly once; nothing is emitted on mount, on an unchanged revision, or when already on page one. A newrowsarray by itself never resets the page. - The reset never touches the selection: selected ids survive filter changes, disappearing rows and the clear action.
- After the built-in clear action brings content back, focus moves to the view container (the activated button unmounts with the panel).
Accessibility
Section titled “Accessibility”- Card view is a labelled list of
Cards; the column dropdown is a Popover of checkboxes; tabs follow the WAI-ARIA tabs pattern. - Selection checkboxes are native inputs with screen-reader-only names; the
select-all reflects a partial page with the native
indeterminatestate. Selected rows carrydata-selectedfor styling. - The no-results state is a
role="status"Empty State. A separate polite live region, outside the table, announces the result count (“3 results”) when filtering changes it. It stays silent on the first render, when the count is unchanged and when rows arrive with no filtering behind them. The no-results state is said once, by its status. No live region wraps the table itself. - A table wider than its card scrolls inside the card. The card takes
tabindex="0",role="region"and a name (the title, else the caption) only while it overflows, so the keyboard can scroll it and a table that fits adds no tab stop (WCAG 2.2 1.4.10, 2.1.1).
Example
Section titled “Example”<TableSet title="Customers" {columns} {rows} configurable allowViewToggle pageSize={10} />In React, toolbar takes markup and renderCell replaces the cell snippet.
Every stateful prop is a controllable mirror, so a parent that holds the
selection passes it back down:
<TableSet title="Customers" columns={columns} rows={filteredRows} pageSize={10} toolbar={<SearchField label="Filter customers" hideLabel onValueChange={setQuery} />} filtersActive={query !== ""} totalRowCount={customers.length} onClearFilters={() => setQuery("")} selectionMode="multiple" selectedRowIds={selected} onSelectedRowIdsChange={setSelected} getRowLabel={(row) => String(row.name)}/>Themeable via --ds-table-*.