Data Table

Import

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@timelycare/helix-ui"
import { Badge } from "@timelycare/helix-ui"
import { Checkbox } from "@timelycare/helix-ui"
import { Button } from "@timelycare/helix-ui"
import { Input } from "@timelycare/helix-ui"

Props

// Built with TanStack Table — configure via column definitions
interface ColumnDef<TData> {
  accessorKey?: string
  header: string | (({ column }) => React.ReactNode)
  cell?: ({ row }) => React.ReactNode
  enableSorting?: boolean
  enableHiding?: boolean
}

Design Tokens

Table Container

Header Row (TableHead)

Table Cell

Checkbox Column

Action Column

Sortable Header Button

Toolbar

Pagination/Caption

Cell Variants

Badge Cell Mapping

Badges in table cells must always use Helix outline primitive variants. Do not use shadcn-style default, secondary, destructive, or outline variants in table contexts.

Do not hand-code badge-like <span> elements — always use the <Badge> component to ensure consistent pill-shape (rounded-full), typography (text-xs font-semibold), and theme-aware colors.

Header Variants

States

Icons

Sort icon: size-4 ml-2 (ArrowDownUp) Action icon: size-4 (MoreVertical — vertical ellipsis, text-primary)

<Button variant="ghost" onClick={() => column.toggleSorting()}>
  Email <ArrowUpDown className="ml-2 size-4" />
</Button>

Common Patterns

Basic Table Structure

<div className="rounded-md border">
  <Table>
    <TableHeader>
      <TableRow>
        <TableHead className="w-[100px]">Status</TableHead>
        <TableHead>Email</TableHead>
        <TableHead className="text-right">Amount</TableHead>
      </TableRow>
    </TableHeader>
    <TableBody>
      <TableRow>
        <TableCell><Badge variant="outlineSage">Active</Badge></TableCell>
        <TableCell>user@example.com</TableCell>
        <TableCell className="text-right">$2,500.00</TableCell>
      </TableRow>
    </TableBody>
  </Table>
</div>

With Selection & Actions

<TableRow>
  <TableCell><Checkbox /></TableCell>
  <TableCell>Success</TableCell>
  <TableCell>user@example.com</TableCell>
  <TableCell>
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="ghost" className="h-8 w-8 p-0">
          <MoreVertical className="h-4 w-4" />
        </Button>
      </DropdownMenuTrigger>
    </DropdownMenu>
  </TableCell>
</TableRow>

Toolbar & Pagination

<div className="flex items-center py-4">
  <Input placeholder="Filter emails..." className="max-w-sm" />
  <DropdownMenu>/* Column visibility */</DropdownMenu>
</div>
<Table>/* ... */</Table>
<div className="flex items-center justify-between py-4">
  <span className="text-sm text-muted-foreground">
    0 of 5 row(s) selected.
  </span>
  <div className="space-x-2">
    <Button variant="outline" size="sm">Previous</Button>
    <Button variant="outline" size="sm">Next</Button>
  </div>
</div>

Accessibility

• Built on TanStack Table — requires manual a11y implementation
• Use semantic <table>, <thead>, <th>, <tbody> structure
• Keyboard: Tab to sortable headers, Enter/Space to sort
• Screen reader: add aria-sort to sortable column headers
• Row selection: use aria-selected on selected rows

Gotchas

See Also

• Related Components: Table (static table), Badge (status cells), Pagination (table pagination)
• Accessibility: Data Tables Accessibility — Table ARIA and keyboard patterns
• Patterns: Table Behavior — Row interactivity, action placement, visual state rules

Last updated: May 1, 2026