Data Table

Basic usage

Three required props carry the whole thing: columns (which is also the column order), rows, and getRowId, whose return value is both the React key and the selection key. Everything else is opt-in.

Sorting

A sortable header cycles through ascending → descending → unsorted. The third stop is deliberate: it lets a user return to the order the server sent without reloading the page, which is why onSortChange is typed to receive null. The header button only appears when a column is sortable and the table has an onSortChange — a shared column definition can stay inert on a read-only screen.

The unsorted icon is not dimmed. It sits inside a button that is still operable, so opacity-50 would not be exempt from the 3:1 threshold of WCAG 1.4.11 — measured against the header row it comes out at 1.98:1 light and 2.23:1 dark. Left at text-muted-foreground it is 4.89:1 and 4.86:1. The sorted state stays distinguishable anyway: the button switches to text-foreground and the icon changes shape.

Row selection

selectable adds a 44px checkbox column pinned to the left. The selection itself is an array of getRowId values that you own. The header checkbox reports indeterminate when only some rows are selected, and select-all only ever touches rows that isRowSelectable allows — locked rows are never swept in and never swept out.

Clicking a checkbox never triggers onRowClick: the cell wraps the checkbox in a span that stops propagation, so ticking a row does not also open it.

Column visibility

DataTableColumnToggle is a separate component so it can live on the page toolbar rather than inside the table. Both halves read the same visibleColumnIds state. Columns marked hideable: false — the identifying column, here Invoice — never appear in the menu, and the menu refuses to hide the last remaining column.

Pinned columns and sticky header

Scroll the table below sideways and downwards. The identifier stays on the left, the amount on the right, and the header stays on top. width is required on every pinned column: the sticky left/right offsets are accumulated from those numbers, so a missing width stacks pinned columns on top of one another. The vertical scroll needs a height, which is what containerClassName="max-h-72" is doing here.

Pinned cells take their fill from the row with bg-inherit, and CSS inherits background-color from the direct parent — which is why the header fill sits on the <tr>, not the <thead>. The same rule is the reason no state in this table is signalled with a translucent background: any alpha on the row is inherited by the pinned cell and the columns underneath show straight through it while you scroll.

Opening a row

Passing onRowClick puts the row into the tab order and wires Enter and Space, because opening a record must not be a mouse-only affordance. Tab into the table below and press Enter. Use isRowActive to mark whatever is currently open next to it.

• The row keeps its implicit role="row"; no role="button" is added. That role would override the row role and a screen reader would lose the table structure — row and column counts, column headers. The row stays a row and merely becomes activatable.
• Key presses are only honoured when the <tr> itself has focus. Enter or Space on a checkbox, button or link inside a cell already means something else, and bubbling would open the record by accident.
• The focus ring is drawn with outline and a negative offset, not ring: box-shadow is not painted on a <tr> in a border-collapse table, and a positive offset would be clipped by the scroll container. Its colour is foreground, not the brand ring — gold on card is about 1.9:1, under the 3:1 that WCAG 1.4.11 asks of a non-text indicator.
• isRowActive tints each cell with --accent, the same fill a selected row gets and the one DataGrid uses, so every table in the package marks a row the same way. The tint goes on the cells, not the row: an opaque fill on each <td> keeps pinned cells solid while you scroll and wins over the even-row stripe, where a class on the <tr> would lose. No border either, so opening a row does not make the table jump.

Density and stripes

density is a local override of the app-wide density axis, not a second class table. It rewrites --row-py and --table-head-h on the <table> element, which is what keeps the header shrinking together with the body — and lets one table be compact while the rest of the app stays comfortable.

The override only runs one way. Only density="compact" writes those two variables; the default "comfortable" writes nothing at all and simply inherits whatever <html data-density="compact"> says. A table can therefore be denser than the app around it, never looser.

striped defaults to false: stripes help you track a row across a long, wide table and are pure noise on a short one, so it is a per-screen decision rather than a package default. The stripe uses the opaque --table-row-stripe token. It is declared at table level, so the generated selector is tbody tr:nth-child(even) at specificity (0,2,2) — it beats and replaces the row's own bg-card (0,1,0) rather than layering over it. A translucent stripe would therefore leave even rows with nothing opaque beneath them, and pinned cells inheriting that alpha would go see-through. The same specificity maths is why you cannot mark a row with a plain background class on a striped table: it loses on every even row.

Loading and empty states

loading replaces the body with loadingRowCount skeleton rows shaped like the real columns, and sets aria-busy on the table. When the request comes back empty, the built-in EmptyState uses labels.emptyTitle and labels.emptyDescription; pass empty when it needs an action.

EmptyState takes the icon component: icon={Inbox}, never icon={<Inbox />}. A Lucide icon is a forwardRef object rather than a function, so component and element cannot be told apart at runtime; the shared IconComponent type makes the compiler catch it instead of failing quietly. If you need an arbitrary node — an illustration — use the media slot.

The labels contract

Every string — including the four aria-label strings that only a screen reader ever hears — comes from the dataTable namespace of the nearest ComitorLocaleProvider: English without one, Vietnamese under locale="vi". Language is set once, at the root; labels is for wording on top of it — no fork, no wrapper. Below, one empty table three ways: untouched, under the Vietnamese provider, and under it with a single labels key, which wins.

Three rules govern the bag, and they are the same across TablePaginationLabels, SearchFilterBarLabels and ShellLabels:

• The prop is Partial<>. The component merges it over the provider's table, so overriding one key keeps the rest — in the provider's language, as the third table shows.
• Keys that interpolate a number or a unit are functions, not strings with placeholders. DataTableLabels happens to have none — all seven keys are plain strings — but its sibling TablePaginationLabels does, and the reason is on that page.
• A standalone prop beats labels. DataTableColumnToggle keeps a label prop because that string varies by content ("Fields", "Columns") while labels.columnToggle varies by language.

import {
  ComitorLocaleProvider,
  DataTable,
  DataTableColumnToggle,
  DEFAULT_DATA_TABLE_LABELS,
  comitorMessagesVi,
} from '@comitor/ui'

// 1. The prop is Partial<DataTableLabels>, merged over the provider's dataTable table,
//    so one key is a legal override and the other six keep the provider's language.
<DataTable {...tableProps} labels={{ emptyTitle: 'No invoices yet' }} />

// 2. A standalone prop beats `labels`. `label` is the per-table string, `labels.columnToggle`
//    is the per-language string — the first wins where both are present.
<DataTableColumnToggle {...toggleProps} label="Fields" labels={{ columnToggle: 'Columns' }} />
// renders "Fields"

// 3. Rewording a key for EVERY table is the provider's job, not each call site's. Keep the
//    object at module level — a new object on every render re-renders every consumer.
const MESSAGES = { dataTable: { emptyTitle: 'Nothing here yet' } }
<ComitorLocaleProvider messages={MESSAGES}>{children}</ComitorLocaleProvider>

// Both built-in tables are plain data in modules with NO 'use client', so a Server Component
// can read them — spread them, diff them, build a list from them.
DEFAULT_DATA_TABLE_LABELS    // English — the component itself reads the provider, not this
comitorMessagesVi.dataTable  // Vietnamese
const withOneChange = { ...comitorMessagesVi.dataTable, emptyTitle: 'Chưa có hoá đơn' }

DEFAULT_DATA_TABLE_LABELS and the DataTableLabels type live in a module that carries no 'use client' directive, on purpose. Everything exported from a client module reaches a Server Component as a client-reference proxy that reads back as undefined without throwing or warning — and plain data constants are exactly what a server page wants to spread, compare and list. The same goes for comitorMessagesVi. The full set of keys, with the English defaults and the Vietnamese table's wording:

Types

All of these are exported from @comitor/ui alongside the components.

type SortDirection = 'asc' | 'desc'

interface DataTableSort {
  columnId: string
  direction: SortDirection
}

type DataTableAlign = 'left' | 'center' | 'right'

interface DataTableColumn<TRow> {
  id: string
  header: ReactNode
  label?: string
  cell: (row: TRow, rowIndex: number) => ReactNode
  sortable?: boolean
  align?: DataTableAlign
  width?: number
  minWidth?: number
  pinned?: 'left' | 'right'
  hideable?: boolean
  headerClassName?: string
  cellClassName?: string
}

DataTable props

DataTableColumn fields

DataTableColumnToggle props

Accessibility

• The table is a real <table> with <th scope="col"> headers — no ARIA grid pattern is layered on top, so browser table navigation keeps working.
• Name every table with aria-label or aria-labelledby. It is mandatory once a page has more than one.
• The sorted column carries aria-sort="ascending" or "descending"; the attribute is absent while unsorted. The sort control is a real <button> inside the header cell, and its icon is aria-hidden.
• While loading, the table sets aria-busy="true".
• Selectable rows get aria-selected and data-state="selected". Each checkbox is named from labels.selectRow / deselectRow, and the header one from selectAllRows / deselectAllRows. Nothing on screen shows those four, so they are the ones to check: a Vietnamese app that forgets the provider looks right and still announces them in English.
• Clickable rows are keyboard operable: tabIndex=0, Enter and Space, and a visible focus outline in foreground (the brand ring colour would only reach ~1.9:1 on card). Space is prevented from scrolling and Enter from submitting an enclosing form.
• The sort state changes the icon shape as well as the colour, so it reads in greyscale (WCAG 1.4.1). Selected rows carry a ticked checkbox as well as the tint.
• Non-text contrast (WCAG 1.4.11) is met by the unsorted sort icon at 4.89:1 / 4.86:1 against the card surface.