DataTable
ComplexData
<co-data-table>DataTable lists records with sorting, row selection with bulk actions, a row menu, expandable rows, empty and loading states, and pagination with rows per page.
import { DataTable } from 'health-components';
Examples
Showcase
Selectable
Row Menu And Expand
With Toolbar
Empty
Loading
Without Pagination
Usage
<DataTable rows={claims} rowKey="id" selectable pageSize={10}
columns={[{ key: "id", label: "Claim", sortable: true }, { key: "status", label: "Status", render: r => <StatusTag kind="claim" status={r.status} /> }]}
bulkActions={ids => <Button size="sm" onClick={() => resubmit(ids)}>Resubmit</Button>}
rowMenu={r => [{ label: "Open Claim", onSelect: () => open(r) }, { divider: true }, { label: "Void Claim", danger: true }]}
renderExpanded={r => <ClaimLines claim={r} />} />
When to use
- Any list of records staff work through: claims, PA queue, patients, appointments, audit log.
When not to use
- Two or three items: a list in a card.
- Phone screens: list rows.
Variants and states
| Variant | What it is |
|---|---|
| sortable | Header buttons with aria-sort. |
| selectable | Checkbox column, select all on page (indeterminate), bulk bar "N selected" with actions and Clear selection. |
| row menu | Kebab per row. |
| expandable | Chevron column opens a detail row. |
| empty | Message across all columns. |
| loading | Skeleton rows. |
| pagination | Rows per page 5, 10, 25, 50; Previous, Page N of M, Next. |
| density | Compact sets cell padding to 4px. |
Accessibility
- Sort buttons sit inside th with aria-sort.
- Row checkboxes are named after the first column ("Select CLM-20871").
- Row menus are named "Actions for CLM-20871".
- Numbers are right aligned with tabular figures.
Do and don't
- Do: Put the status column near the left so it is seen first.
- Do: Keep row actions in the menu and the main action as a link on the record ID.
- Don't: Horizontal scroll inside a modal.
- Don't: Delete as the first item in a row menu.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
columns * | ReadonlyArray<DataTableColumn<T>> | — | Array<{key, label, sortable?, align?, render?, sortValue?}>. Required |
rows * | ReadonlyArray<T> | — | The records. Required |
rowKey | (keyof T & string) | ((row: T) => DataTableRowId) | "id" | Field that identifies a row, or a function returning the id |
selectable | boolean | false | Row checkboxes and a select-all-on-page checkbox |
selected | DataTableRowId[] | — | Selected row ids (controlled) |
defaultSelected | DataTableRowId[] | [] | Initially selected row ids (uncontrolled) |
onSelectedChange | (ids: DataTableRowId[]) => void | none | Called with the new selected ids |
bulkActions | (selectedIds: DataTableRowId[]) => ReactNode | none | (selectedIds) => node: actions shown in the bulk bar while rows are selected |
rowMenu | (row: T) => MenuItem[] | none | (row) => MenuItem[]: a kebab menu at the end of each row |
renderExpanded | (row: T) => ReactNode | none | (row) => node: makes rows expandable |
expanded | DataTableRowId[] | — | Expanded row ids (controlled) |
defaultExpanded | DataTableRowId[] | [] | Initially expanded row ids (uncontrolled) |
onExpandedChange | (ids: DataTableRowId[]) => void | none | Called with the new expanded ids |
loading | boolean | false | Shows skeleton rows and hides pagination |
emptyText | ReactNode | "No records match your search or filters." | Text when there are no rows |
emptyState | ReactNode | none | Node when there are no rows (an EmptyState); wins over emptyText |
pageSize | number | 10 | Initial rows per page |
pageSizes | readonly number[] | false | [5, 10, 25, 50] | Rows-per-page choices, or false to hide the selector |
onPageSizeChange | (size: number) => void | none | Called with the new rows per page |
page | number | — | Current page, 1-based (controlled) |
defaultPage | number | 1 | Initial page (uncontrolled) |
onPageChange | (page: number) => void | none | Called with the new page |
pagination | boolean | true | Paginate the rows |
sort | DataTableSort | null | — | Active sort (controlled); null for none |
defaultSort | DataTableSort | null | none | Initial sort {key, dir} (uncontrolled) |
onSortChange | (sort: DataTableSort | null) => void | none | Called with the new sort |
toolbar | ReactNode | none | Toolbar above the table (search, filters); replaced by the bulk bar while rows are selected |
caption | string | none | Screen reader caption |
Also accepts native attributes, including defaultChecked, defaultValue, autoFocus, onInput, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-data-table>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
Angular template
<co-data-table selectable loading [columns]="columns" (co-selected-change)="onSelectedChange($event.detail)"></co-data-table>
| Kind | Name | Description |
|---|---|---|
| property / JSON attribute | columns | Array<{key, label, sortable?, align?, render?, sortValue?}>. Required |
| property / JSON attribute | rows | The records. Required |
| property / JSON attribute | row-key / rowKey | Field that identifies a row, or a function returning the id; default "id" |
| attribute | selectable | Row checkboxes and a select-all-on-page checkbox; default false |
| property / JSON attribute | selected | Selected row ids (controlled) |
| property / JSON attribute | default-selected / defaultSelected | Initially selected row ids (uncontrolled); default [] |
| property / JSON attribute | expanded | Expanded row ids (controlled) |
| property / JSON attribute | default-expanded / defaultExpanded | Initially expanded row ids (uncontrolled); default [] |
| attribute | loading | Shows skeleton rows and hides pagination; default false |
| attribute | page-size / pageSize | Initial rows per page; default 10 |
| property / JSON attribute | page-sizes / pageSizes | Rows-per-page choices, or false to hide the selector; default [5, 10, 25, 50] |
| attribute | page | Current page, 1-based (controlled) |
| attribute | default-page / defaultPage | Initial page (uncontrolled); default 1 |
| attribute | pagination | Paginate the rows; default true |
| property / JSON attribute | sort | Active sort (controlled); null for none |
| property / JSON attribute | default-sort / defaultSort | Initial sort {key, dir} (uncontrolled); default none |
| attribute | caption | Screen reader caption; default none |
| attribute | default-checked / defaultChecked | |
| property / JSON attribute | default-value / defaultValue | |
| attribute | auto-focus / autoFocus | |
| property (function) | rowMenu | (row) => MenuItem[]: a kebab menu at the end of each row; default none |
| event | co-selected-change | Called with the new selected ids; default none (React: onSelectedChange) |
| event | co-expanded-change | Called with the new expanded ids; default none (React: onExpandedChange) |
| event | co-page-size-change | Called with the new rows per page; default none (React: onPageSizeChange) |
| event | co-page-change | Called with the new page; default none (React: onPageChange) |
| event | co-sort-change | Called with the new sort; default none (React: onSortChange) |
| event | co-input | (React: onInput) |
| slot | bulk-actions | (selectedIds) => node: actions shown in the bulk bar while rows are selected; default none Plain text also works as the `bulk-actions` attribute. |
| slot | render-expanded | (row) => node: makes rows expandable; default none Plain text also works as the `render-expanded` attribute. |
| slot | empty-text | Text when there are no rows; default "No records match your search or filters." Plain text also works as the `empty-text` attribute. |
| slot | empty-state | Node when there are no rows (an EmptyState); wins over emptyText; default none Plain text also works as the `empty-state` attribute. |
| slot | toolbar | Toolbar above the table (search, filters); replaced by the bulk bar while rows are selected; default none Plain text also works as the `toolbar` attribute. |