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 paints an inset rule in --app-accent-ink on each cell (6.14:1 on card in light, 9.61:1 in dark). Not a background, for the two reasons above and below; not an outline on the row, because pinned cells sit on a higher stacking layer and would clip it. Because it is a shadow it adds no height, 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 the package ships is Vietnamese, including the four aria-label strings that only a screen reader ever hears. An English app overrides them through labels — no fork, no wrapper. Three rules govern this bag, and they are the same across TablePaginationLabels, SearchFilterBarLabels and ShellLabels:

• The prop is Partial<>. The component always spreads { ...DEFAULT_DATA_TABLE_LABELS, ...labels }, so overriding one key keeps the rest.
• 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 { DataTableColumnToggle, DEFAULT_DATA_TABLE_LABELS } from '@comitor/ui'
import type { DataTableLabels } from '@comitor/ui'

// 1. The prop is Partial<DataTableLabels>. The component always spreads
//    { ...DEFAULT_DATA_TABLE_LABELS, ...labels }, so one key is a legal override.
<DataTableColumnToggle {...toggleProps} labels={{ columnToggle: 'Columns' }} />

// 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. Declare the full English set once and share it across every table in the app.
export const EN_TABLE_LABELS: Partial<DataTableLabels> = {
  selectAllRows: 'Select all visible rows',
  deselectAllRows: 'Clear the selection',
  selectRow: 'Select row',
  deselectRow: 'Deselect row',
  emptyTitle: 'No records yet',
  emptyDescription: 'This list is currently empty.',
  columnToggle: 'Columns',
}

// DEFAULT_DATA_TABLE_LABELS lives in a module with NO 'use client' on purpose, so a Server
// Component can read it — spread it, diff it, build a list from it.
const withOneChange = { ...DEFAULT_DATA_TABLE_LABELS, 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 full set of keys and their Vietnamese defaults:

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 — so translate those four even though nothing on screen shows them.
• 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.
• Colour is never the only signal. The sort state changes the icon shape as well as the colour, and the active row is a 2px rule rather than a tint — both readable in greyscale, per WCAG 1.4.1.
• Non-text contrast (WCAG 1.4.11) is met by the unsorted sort icon at 4.89:1 / 4.86:1, and by the active-row rule at 6.14:1 / 9.61:1 against the card surface.