DATA AND TABLES

Data table

Draft

An enhanced table component with built-in sorting, filtering, row selection, and pagination.

Usage

Name	Email	Role
Alice Park	alice@example.com	Admin
Bob Chen	bob@example.com	Editor
Carol Diaz	carol@example.com	Viewer

Common alternative names

Grid, data grid, spreadsheet

Usage guidelines coming soon.

Specs

Specs coming soon.

Content

Content guidelines coming soon.

Status & changelog

Status & changelog coming soon.

Code

---

Usage

import { DataTable } from '@arch-ui/components';

const columns = [
  { key: 'name', header: 'Name', sortable: true },
  { key: 'email', header: 'Email', sortable: true },
  { key: 'role', header: 'Role', filterable: true },
];

const rows = [
  { id: '1', name: 'Alice Park', email: 'alice@example.com', role: 'Admin' },
  { id: '2', name: 'Bob Chen', email: 'bob@example.com', role: 'Editor' },
  { id: '3', name: 'Carol Diaz', email: 'carol@example.com', role: 'Viewer' },
];

function UserTable() {
  return (
    <DataTable
      caption="Team members"
      columns={columns}
      data={rows}
      selectable
    />
  );
}

---

Expected props

Prop	Type	Default	Description
caption	string	--	Accessible description of the table. Required.
columns	ColumnDef[]	--	Column definitions controlling headers, sorting, and filtering. Required.
data	Row[]	--	Array of row objects. Each row should have a unique id. Required.
selectable	boolean	false	When true, renders checkboxes for row selection.
onSelectionChange	(selectedIds: string[]) => void	--	Called when the selection changes.
sortable	boolean	false	Global toggle for column sorting (individual columns can override).
paginated	boolean	false	When true, renders a Pagination control below the table.
pageSize	number	10	Number of rows per page when paginated is true.
emptyState	ReactNode	--	Content shown when data is empty.
className	string	--	Additional class names.

ColumnDef

Prop	Type	Description
key	string	The property name in the row object.
header	string	Column header label.
sortable	boolean	When true, the column header is clickable for sorting.
filterable	boolean	When true, a filter control appears for this column.
width	string	Optional fixed width (e.g., '200px').
align	'start' | 'center' | 'end'	Cell content alignment.
render	(value, row) => ReactNode	Custom cell renderer.

---

Sorting

Columns marked sortable: true render a clickable header. Clicking toggles between ascending, descending, and unsorted states. The current sort state is indicated by an arrow icon.

const columns = [
  { key: 'name', header: 'Name', sortable: true },
  { key: 'created', header: 'Created', sortable: true },
];

---

Row selection

When selectable is true, a checkbox column is prepended. A header checkbox toggles all rows. Selected row IDs are reported via onSelectionChange.

<DataTable
  caption="Select items"
  columns={columns}
  data={rows}
  selectable
  onSelectionChange={(ids) => console.log('Selected:', ids)}
/>

---

Pagination

Enable built-in pagination for large data sets. The Pagination component renders below the table.

<DataTable
  caption="Transactions"
  columns={columns}
  data={transactions}
  paginated
  pageSize={25}
/>

---

Custom cell rendering

Use the render function on a column definition to customise how cell values are displayed.

const columns = [
  { key: 'status', header: 'Status', render: (value) => <Badge>{value}</Badge> },
];

---

Empty state

Provide an emptyState node to display when the data array is empty.

<DataTable
  caption="Search results"
  columns={columns}
  data={[]}
  emptyState={<p>No results found. Try adjusting your filters.</p>}
/>

---

Accessibility

• Built on the base Table component, inheriting its semantic HTML structure and required caption.
• Sortable column headers use aria-sort (ascending, descending, or none).
• Row selection checkboxes have aria-label values such as "Select row Alice Park" and "Select all rows".
• The header checkbox uses aria-checked="mixed" when some but not all rows are selected.
• Pagination controls use the Pagination component's built-in ARIA attributes.