Table

v1.1.6

Ready for Production

Catalyst Table wraps native semantic HTML table elements with CVA coloration and textAlign variants and design token integration — giving you a fully accessible, consistently styled table with transparent and colored options for headers, body cells, and footers.

Installation

npm install @pmi/catalyst-table

import {
  TableRoot,
  TableHeader,
  TableBody,
  TableFooter,
  TableHead,
  TableRow,
  TableCell,
  TableCaption,
} from '@pmi/catalyst-table';

Variants

Transparent

Omit coloration (or set it to "transparent", the default) on TableHead and TableCell so they don't add their own background fill. TableBody still applies its alternating row backgrounds independently of this variant.

API Reference

TableRoot

Root table element (<table>). Renders a rounded bordered container with PMI neutral background and border tokens.

TableHeader

Semantic <thead> section. Accepts all standard HTML thead attributes and forwards ref.

TableBody

Semantic <tbody> section. Sets data-section="tbody" so descendant TableCell elements with coloration="colored" can apply body-specific background and border tokens. Accepts all standard HTML tbody attributes.

TableFooter

Semantic <tfoot> section. Sets data-section="tfoot" so descendant TableCell elements with coloration="colored" apply footer-specific background and border tokens. Accepts all standard HTML tfoot attributes.

TableRow

Semantic <tr> row. Accepts all standard HTML tr attributes and forwards ref.

TableHead

Semantic <th> header cell with coloration and textAlign CVA variants.

TableCell

Semantic <td> data cell with coloration and textAlign CVA variants. The colored variant reads data-section from the parent TableBody or TableFooter to apply the correct section-specific background.

TableCaption

Semantic <caption> element. Required for WCAG 1.3.1 / 4.1.2 compliance — always provide one. Must be the first child of <TableRoot>. Use className="sr-only" to hide it visually. aria-label on <TableRoot> is a valid fallback when <TableCaption> structurally cannot be placed in the DOM, though <TableCaption> is preferred. Accepts all standard HTML caption attributes.

Accessibility

Catalyst Table meets WCAG 2.2 AA standards using native semantic HTML — no custom ARIA management required.

Keyboard Interactions

Table has no interactive elements by default. Screen reader users navigate cells using their AT's virtual cursor; no custom keyboard handling is added by the component.

For wide tables that overflow horizontally, wrap <TableRoot> in a scroll container so keyboard users can scroll without a pointing device:

<div role="region" aria-label="Invoice list" tabIndex={0} className="overflow-x-auto">
  <TableRoot>...</TableRoot>
</div>

ARIA Attributes

Native semantic HTML handles all accessibility requirements automatically:

• <th scope="col"> associates the header with all cells in its column; <th scope="row"> associates it with all cells in its row; scope="colgroup" and scope="rowgroup" are required for grouped multi-level headers.

• For complex tables that use colSpan or rowSpan, scope alone cannot express header relationships. Use id/headers attributes instead:

  <TableHead id="q1" scope="col">
    Q1
  </TableHead>;
  {
    /* ... */
  }
  <TableCell headers="q1">$250.00</TableCell>;

• <caption> announces the table's purpose to screen readers and provides the table's accessible name. It must be the first child of <TableRoot>.

• <thead>, <tbody>, and <tfoot> provide code organization and enable CSS styling; they do not carry accessibility semantics and are not announced by screen readers.

Always provide a <TableCaption>. If it should be visually hidden, use className="sr-only".

Choosing the Right Component

Related

• Data Table