CynosureComponents / Feedback and display
Table
Rows of data with headers. Columns can sort, rows can be selected, and the header can stay in view while the body scrolls.
When to useLink to "When to use"
- Records with the same fields, read across and compared down: members, invoices, logs.
Use something else when:
- there is one record: DescriptionList
- items are visual or uneven: Grid of Cards
- the data is nested: Tree
UsageLink to "Usage"
import { Table } from "@arshad-shah/cynosure";
<Table caption="Team members" rows={members} getRowId={(m) => m.id} columns={columns} />A column shows row[key] unless it has a cell function. align: "end" lines numbers up.
SortingLink to "Sorting"
Mark columns sortable and their headers become buttons (a SortButton): ascending, then descending, then the original order. Sorting compares row[key] (or sortValue(row)): text in the locale's order, numbers as numbers, empty values last. Sort on a server with manualSort: the table then shows and reports the sort through onSortChange without reordering.
SelectionLink to "Selection"
selectable adds a checkbox to each row (named after the row header, "Select Grace") and a select-all that is mixed when some rows are selected. Selected ids are reported in the rows' own order. Ids that are not in rows (another page, or filtered out) stay selected, listed first; the select-all acts on the rows shown.
Sticky headerLink to "Sticky header"
With stickyHeader the body scrolls inside the table up to --cy-table-max-height and the header stays in view. The scroller is a focusable region named by the caption, so keyboard users can scroll it.
PropsLink to "Props"
| Prop | What it does | Type | Default |
|---|---|---|---|
captionRequired | The table's caption: its accessible name, shown above it unless captionHidden. | ReactNode | |
columnsRequired | The columns, in display order. | TableColumn<Row>[] | |
rowsRequired | The data, one entry per row. | Row[] | |
getRowIdRequired | A stable id per row (for selection and React keys). | (row: Row) => string | |
captionHidden | Hides the caption visually; it still names the table. | boolean | |
sort | The current sort (controlled); null is unsorted. | TableSort | null | |
defaultSort | Starting sort when uncontrolled; unsorted when left out. | TableSort | null | |
onSortChange | Called when a sortable header is pressed, with the new sort, or null when it goes back to unsorted. | ((sort: TableSort | null) => void) | |
manualSort | You sort the rows (e.g. on a server); the table only shows and reports the sort. | boolean | |
selectable | Adds a checkbox per row and a select-all in the header. | boolean | |
selected | Ids of the selected rows (controlled). | string[] | |
defaultSelected | Ids of the rows selected at the start when uncontrolled. | string[] | |
onSelectionChange | Called when a row's checkbox or select-all changes, with the selected ids: those not in rows (another page, filtered out) first, then the shown ones in row order. Select-all acts on the shown rows only. | ((ids: string[]) => void) | |
stickyHeader | The header stays visible while the body scrolls inside the table. | boolean | |
size | Cell padding and text size. Default "md". | Size | "md" |
labels | Replace the built-in English text: the checkbox names and the empty message. | Partial<TableLabels> | |
className | Added to the root element, for layout. | string | |
style | Layout only. Restyle through --cy-table-* tokens. | CSSProperties |
Generated from the type definitions in @arshad-shah/cynosure 0.5.0.
Behaviour and accessibilityLink to "Behaviour and accessibility"
- Semantics: a native table with a caption; column headers, and a row header per row (the first column, or the one marked
rowHeader), so screen readers announce context with every cell. - Sorting: sortable headers carry
aria-sortand contain a button; Enter or Space sorts. - Selection: native checkboxes in the first column; Space toggles; the select-all reports "mixed".
- Empty: one cell across all columns says so (
labels.empty). - Touch: sort buttons have a 44px hit area on touch screens.
- Contrast: headers, cells and selected rows keep 4.5:1 in light and dark modes.
- Direction: columns follow the text direction; end-aligned cells sit at the inline end.
ThemingLink to "Theming"
Tokens: --cy-table-header-background, --cy-table-selected-background and --cy-table-max-height.
RelatedLink to "Related"
These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.