Data Table

v1.0.9

Ready for Production

Catalyst Data Table provides a suite of composable UI components that integrate with TanStack Table v8 — giving you styled, accessible table primitives for sorting, expanding, row/column pinning, column resizing, row selection, and pagination while TanStack Table manages all state and logic.

Installation

npm install @pmi/catalyst-data-table

Note: @tanstack/react-table (v8.20.6) is a direct dependency bundled with this package — no separate install required.

import { useReactTable, getCoreRowModel, type ColumnDef } from '@tanstack/react-table';
import {
  DataTableRoot,
  DataTableRow,
  DataTableHead,
  DataTableCell,
  DataTableFlexRender,
} from '@pmi/catalyst-data-table';

The Data Table is built on a compound component pattern. The typical JSX structure is:

<DataTableRoot table={table}>
  <thead>
    <tr>
      <DataTableHead header={header}>
        <DataTableFlexRender header={header} />
      </DataTableHead>
    </tr>
  </thead>
  <tbody>
    <DataTableRow row={row}>
      <DataTableCell cell={cell}>
        <DataTableFlexRender cell={cell} />
      </DataTableCell>
    </DataTableRow>
  </tbody>
</DataTableRoot>

Data Table components require a TanStack Table instance created with useReactTable. Enable features by composing row models:

import {
  useReactTable,
  getCoreRowModel,
  getSortedRowModel,
  getExpandedRowModel,
  getPaginationRowModel,
  type ColumnDef,
} from '@tanstack/react-table';

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),        // sorting
  getSubRows: (row) => row.subRows,              // expanding
  getExpandedRowModel: getExpandedRowModel(),    // expanding
  getPaginationRowModel: getPaginationRowModel(), // pagination
  columnResizeMode: 'onChange',                  // column resizing
});

Always wrap data and columns in useMemo to prevent unnecessary re-renders.

Common Patterns

Sorting

Click column headers to toggle ascending, descending, or no sort. The sequence is asc → desc → none.

Expanding

Click the chevron icon to expand a row and reveal sub-rows. Sub-rows display with adjusted background color reflecting their depth.

Row Selection

Select rows by clicking the checkbox or the row itself. The header checkbox toggles all rows; when some rows are selected it enters an indeterminate state.

Row Pinning

Pin rows to the top or bottom of the table. Pinned rows remain sticky during vertical scroll.

Column Pinning

Pin columns to the left or right. Pinned columns stay fixed during horizontal scroll.

Column Resizing

Drag the resizer handle at a column's edge to adjust its width. Double-click the resizer to reset to the default size.

The resizer button is fully keyboard-operable: focus it with Tab, then use ArrowLeft / ArrowRight to adjust the column width in 10 px steps. Hold Shift while pressing an arrow key to move in 50 px steps. Press Enter to reset the column to its default width. This keyboard behaviour is required for accessibility compliance (WCAG 2.2 SC 2.1.1).

Pagination

Client-side pagination using TanStack Table's getPaginationRowModel, combined with Catalyst Pagination and Select components.

API Reference

Data Table is a compound component built on TanStack Table v8. Each part wraps a native HTML element and accepts a TanStack Table instance to drive its behaviour. The sections below summarize the API surface for each part.

DataTableRoot

Container that links the table UI to the TanStack Table instance. Forwards ref to HTMLTableElement. Extends all standard HTML <table> props.

DataTableHead

Renders header cells with sorting, pinning, and resizing support. Forwards ref to HTMLTableCellElement. Automatically sets aria-sort based on sort state. Provides data-sorted and data-pinned data attributes for styling. Extends all standard HTML <th> props.

DataTableRow

Renders rows with selection, expansion, and pinning support. Forwards ref to HTMLTableRowElement. Adds data-selected, data-subrow, and data-pinned data attributes. Extends all standard HTML <tr> props.

DataTableCell

Renders cells with column-pinning support. Forwards ref to HTMLTableCellElement. Adds data-row-pinned and data-column-pinned data attributes. Extends all standard HTML <td> props.

DataTableFlexRender

Dynamically renders cell or header content using TanStack Table's flexRender. Forwards ref to HTMLDivElement. Provide either cell or header — not both. Extends all standard HTML <div> props.

DataTableSorting

Button that toggles column sorting when clicked. Must be used inside DataTableHead. Disabled automatically when the column cannot be sorted. Forwards ref to HTMLButtonElement. Extends all standard HTML <button> props.

DataTableExpand

Button that toggles row expansion for hierarchical data. Returns null when the row cannot be expanded. Forwards ref to HTMLButtonElement. Adds data-expanded data attribute. Extends all standard HTML <button> props.

DataTableRowPin

Button that pins or unpins a row to the top or bottom. Returns null when the row cannot be pinned or is already in the requested position. Forwards ref to HTMLButtonElement. Extends all standard HTML <button> props.

DataTableColumnPin

Button that pins or unpins a column to the left or right. Must be used inside DataTableHead. Returns null when the column cannot be pinned or is already in the requested position. Forwards ref to HTMLButtonElement. Extends all standard HTML <button> props.

DataTableColumnResizer

Draggable handle for adjusting column width. Must be used inside DataTableHead. Returns null when the column cannot be resized. Double-click to reset to default size. Forwards ref to HTMLButtonElement. Extends all standard HTML <button> props.

Accessibility

Data Table is designed to meet WCAG 2.2 AA standards through semantic HTML and ARIA attributes.

Keyboard Interactions

ARIA

• DataTableHead automatically applies aria-sort="ascending", aria-sort="descending", or aria-sort="none" on sortable columns (WCAG 2.2 SC 4.1.2).
• DataTableHead sets scope="col" and role="columnheader" on every header cell for correct screen reader table navigation.
• All interactive controls (DataTableSorting, DataTableExpand, DataTableRowPin, DataTableColumnPin, DataTableColumnResizer) render as <button> elements and are keyboard reachable.
• Always provide visible labels or <span className="sr-only"> on icon-only controls so screen readers can announce their purpose (e.g. "expand row 1", "pin column firstName left").
• Row selection checkboxes should carry aria-label values that identify the row (e.g. aria-label="select row 1").

Choosing the Right Component

Related

• Pagination
• Checkbox
• Select
• Button