Table

Visual Hierarchy

Use TableHead with font-medium to clearly distinguish headers from data rows. Apply text-right to numeric columns (amounts, quantities) for easier scanning. Use font-medium on the primary identifier cell in each row (e.g., invoice number, name).

Spacing & Layout

Table cells use p-2 padding by default. Set explicit widths on header cells (className="w-[100px]") to prevent column shifting during data updates. The table container provides overflow-x-auto for horizontal scrolling on smaller viewports. Wrap the table in a rounded-lg border border-border container for a polished appearance.

Responsive Behavior

The Table component automatically enables horizontal scrolling when content overflows. On mobile, consider hiding less critical columns with className="hidden md:table-cell". For narrow screens, evaluate whether a list-based layout (using Card) would provide a better reading experience.

Color & Contrast

Row hover state uses hover:bg-muted/50 for subtle feedback. Selected rows use data-[state=selected]:bg-muted for clear visual indication. The footer uses bg-muted/50 to visually separate summary rows from data. Ensure all text content meets WCAG 2.1 AA contrast ratios against both default and striped row backgrounds.

Keyboard Navigation

• Tab — Move focus to the next interactive element within the table (links, buttons, checkboxes)
• Shift + Tab — Move focus to the previous interactive element
• Enter or Space — Activate focused buttons or checkboxes within cells
• Arrow Keys — Navigate within dropdown menus triggered from action cells

Screen Reader Support

• Use TableCaption to provide a descriptive summary of the table content
• Add scope="col" on column headers and scope="row" on row headers for complex tables
• Screen readers announce the table structure (rows and columns) and navigate cell-by-cell
• Avoid using aria-hidden on cells that contain meaningful data

Sortable Columns

• Use aria-sort="ascending" or aria-sort="descending" on sortable column headers
• Provide a visual sort indicator (arrow icon) that matches the aria-sort value
• Announce sort changes to assistive technology using an aria-live region

Selection States

When rows are selectable, use role="checkbox" with aria-checked on selection controls. The data-state="selected" attribute provides visual feedback while the checkbox communicates state to assistive technology. Use a "Select all" checkbox in the header with aria-label="Select all rows".

ARIA Attributes

{/* Always provide a caption for screen readers */}
<Table>
  <TableCaption>Monthly revenue by product line.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead scope="col">Product</TableHead>
      <TableHead scope="col">Revenue</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>...</TableBody>
</Table>

{/* Sortable column headers */}
<TableHead
  scope="col"
  aria-sort={sortDir === "asc" ? "ascending" : "descending"}
>
  <Button variant="ghost" onClick={toggleSort}>
    Name <ArrowUpDown className="ml-2 size-4" />
  </Button>
</TableHead>

{/* Row headers for two-dimensional data */}
<TableRow>
  <TableHead scope="row">Q1 2024</TableHead>
  <TableCell>$12,400</TableCell>
  <TableCell>$9,800</TableCell>
</TableRow>