Data Table

When to use it

Use the data table when the record set itself is the work: scanning, comparing, sorting, filtering, selecting, and acting on rows.

Anatomy

The table owns the relationship between controls, result state, headers, rows, and actions. Individual primitives still own their control behavior.

• Table title or caption

  Required

  Name the record set in plain language. The title or caption tells assistive technology users what the table contains.

  Use a visible heading near the table and a caption or aria-labelledby connection for the table element.

• Toolbar

  Conditional

  Search, filters, saved views, export, and create actions live above the table when they change or act on the result set.

  Keep active filters visible. Do not hide the reason a table changed.

• Column headers

  Required

  Headers are short nouns or noun phrases. Sortable headers expose both the action and current sort state.

  Use th scope="col" and aria-sort on the sorted column.

• Rows and cells

  Required

  Cells stay aligned to their headers. Status cells include readable text, not color alone.

  Use semantic table markup for comparable data; avoid div grids for ordinary tables.

• Selection and row actions

  Conditional

  Selectable tables show a labeled checkbox per row, a selected count, and actions that apply to the selection.

  Do not make the entire row the only interactive target when individual links, checkboxes, or actions are present.

• Pagination and result count

  Conditional

  Large result sets show how many records exist, what page is visible, and how users move through pages.

  Keep pagination controls keyboard reachable and preserve filters while changing pages.

Variants

Choose the table variant by the job: compare rows, select work, or recover from an empty filtered result.

Examples

The previews show table controls, row states, active filters, and empty-state recovery in realistic product context.

Voice and content

Table copy should support scanning. Labels need to be stable, short, and specific enough to explain the data.

• Use noun-first column labels

  Column headers should name the attribute: "Renewal date," "Owner," "Status." Avoid instructions such as "Click to renew."

• Put units and formats where users compare

  If a column needs units, date format, or currency, make that clear in the header or cell formatting.

• Write status as text

  Badges and icons can help scanning, but the cell still needs words such as "Approved," "Pending," or "Needs review."

• Name table actions by outcome

  "Approve selected" and "Export vendors" beat vague labels such as "Apply" or "Go."

Accessibility

Table accessibility depends on semantic markup, labeled controls, visible state, and predictable focus when the result set changes.

• Use semantic table structure

  Use table, caption, thead, tbody, th, and td for comparable data so headers and cells stay connected.

• Expose sort state

  Set aria-sort on the currently sorted header and make sortable headers keyboard accessible.

• Label selection controls

  Header and row checkboxes need specific accessible labels such as "Select all vendors" and "Select Acme Services LLC."

• Do not rely on color alone

  Status, selected state, errors, and warnings need text or icons in addition to color.

• Preserve focus through table state changes

  Filtering, pagination, and bulk actions should keep focus predictable and announce important result-count changes.

Implementation notes

The table pattern coordinates state, controls, and semantic structure. It should not become a collection of unrelated divs and buttons.

• Compose controls from primitives

  Use Button, Checkbox, Link, Badge, Tooltip, Text Input, and Select before adding custom table controls.

  Primitives: Button, Checkbox, Link, Badge, Tooltip, Text Input, Select

• Keep table state explicit

  Represent sort, filter, search, page, and selection state in code and, when useful, in the URL so refresh and sharing preserve the same view.

• Reuse the empty-state pattern

  No-data and no-results states should follow the Empty State pattern. Filtered empties explain which controls caused the result.

  Primitives: Button

• Protect comparison on small screens

  Prefer horizontal scrolling with clear headers for dense comparison. Only transform rows into cards when the comparison job still works.

Review checklist

Use this as the acceptance gate before approving a data table.

• The table has a title or caption that names the record set.
• Column headers are semantic, short, and connected to their cells.
• Sortable columns expose current sort state with aria-sort.
• Filters, search, result count, and pagination remain visible when they affect the result set.
• Selection controls are labeled and bulk actions show selected count.
• Empty and filtered-empty states explain what happened and how to recover.
• Status and selected states do not rely on color alone.

Related

• Patterns Overview - what a pattern is and the shape every pattern page follows.
• Empty State - the no-data and no-results states this pattern relies on.
• Generic empty-state copy, Color-only state, and No focus outline - the common failures this pattern must avoid.
• Button, Checkbox, Link, Badge, Tooltip, Text Input, Select - primitives used by table controls and row content.