Table accessibility

WCAG 2.1 AA requirements

Semantic HTML

• Table uses native <table>, <thead>, <tbody>, <tfoot>, <tr>, <th>, <td>, and <caption> elements. Screen readers announce these correctly without extra ARIA.
• <th> elements are used for column headers — never <td> with bold styling.

Caption

• Use TableCaption to provide a visible description of the table. This maps to <caption>, which is the native mechanism for labelling a table.
• If you cannot use a visible caption, provide aria-label or aria-labelledby on the Table root.

Column headers

• TableHead renders <th> with scope="col" implied by placement inside <thead>. This allows screen readers to associate data cells with their column header.

Row headers

• If your first column acts as a row identifier (e.g., invoice number), add scope="row" to those TableHead cells for better screen-reader association.

Striped rows

• Striped rows use a subtle bg-muted/50 background. The contrast between striped and non-striped rows is decorative — do not rely on color alone to communicate meaning.

Focus and keyboard

• Tables are not focusable by default. If you add interactive elements (buttons, links, checkboxes) inside cells, ensure they are individually focusable and reachable via Tab.

Audit checklist

• Table has a <caption> or aria-label
• Column headers use <th> not styled <td>
• Row headers (if applicable) have scope="row"
• Interactive elements inside cells are keyboard-accessible
• Striped rows do not rely on color alone for meaning
• Table is visible and readable in both light and dark themes