Prepared Docs

Overview

Table is the lightweight, semantic table primitive for presenting structured data you control row-by-row. It prioritizes clarity and accessibility over sorting, filtering, and selection. The mental model is "read-only grid"—a two-dimensional layout where headers and cells are programmatically associated so screen readers can navigate both axes. When the task is "operators interact with this data" (sort, filter, select, paginate), the right component is DataTable; Table stays lean because its job is structure, not behavior. Use it for documentation comparisons, reference matrices, and settings summaries where fewer than a few dozen rows are known up front.

Incident ID	Priority	Caller
PSA-24-001	P1	Morgan Reyes
PSA-24-002	P2	Dana Ortiz
PSA-24-003	P3	Jesse Parks

When to use

For small, static datasets that don't need interactivity

On the order of dozens of rows or fewer, where sort and filter are not meaningful. Reference matrices, comparison grids, and settings recaps fit here.

For documentation-style comparisons

Component prop reference tables, token recipes, feature matrices. The content is authored, not fetched—and the mental model is "read this grid", not "drive this grid".

For custom layouts where you will implement any behavior yourself

When none of DataTable's features apply and you only need the accessible HTML structure.

When not to use

For any interactive data feature

Sort, filter, search, pagination, row selection, row expansion, async loading, column resizing. Use DataTable. Re-implementing those on top of Table is expensive and error-prone.

For responsive cards that replace the table on mobile

Tables with column counts that don't fit narrow viewports need a different presentation on mobile. Design an alternate card layout or switch to a definition-list pattern; Table alone is not the right vehicle.

For very large dynamic lists

Virtualize the data with VirtualizedList or graduate to DataTable. A flat Table with thousands of rows will crater layout performance.

Variants

Concern	Purpose	Emphasis
Column headers vs. data cells	Semantics	Always use proper header cells for columns
Row headers	Row identity	First cell as row header when it names the row
Alignment	Readability	Text left, numerics right, status icons centered
Scrollable wrapper	Overflow	Pair with `Scrollable` for wide or tall tables
Density	Spacing	Default for most content; tighter density for reference matrices

Composition

Table contains TableHeader, TableBody, TableRow, and TableCell variants. Headers establish relationships for assistive technology; row headers let screen reader users navigate two-dimensional data. Keep the markup semantic—do not flatten a table into divs for styling convenience.

Content guidelines

Headers. Short, unique per column; sentence case per form label rules unless the table is documentation-heavy title casing.
Cells. Simple content. Use Text tokens for emphasis rather than ad-hoc styles.
Empty tables. Explain why empty and what to do next ("No entries yet. Add one from the settings panel."). Empty tables without context feel broken.
Internationalization. Watch alignment for RTL languages; test the longest expected column headers inside the target width.
Consistent formatting. Numbers, dates, and currency use the same format within a column. Switching formats mid-column taxes scanning.

Behavior and states

Non-interactive by default. Static tables have no built-in interaction states; if rows become clickable, use Interactable or row-level buttons with clear semantics. Avoid nesting conflicting controls.
Hover. Optional on rows; never rely on hover alone for essential information (touch users will miss it).
Selection, sort, filter. Not available—graduate to DataTable.

Best practices

Keep column order stable across loads. Operators scan by position, and shifting columns breaks muscle memory.
Use consistent number formatting within a column. Mix dollars and cents, or thousands and millions, only when the axis itself is the unit—and label it.
Limit column count. Horizontal scroll is acceptable but should not hide critical identifiers (the first column stays pinned conceptually even when the markup does not).
Use headers for every column and row-level headers where rows have a natural name (incident id, agency name).

Don't

Use Table because the layout "looks grid-like" for non-tabular content. Use CSS Grid or FlexBox.
Put complex forms inside cells without careful focus management. Inline edits are a DataTable feature; in a static Table, open a modal or drawer for the editing surface.
Merge cells in ways that confuse header associations unless the structure truly calls for it (and, when it does, explicitly test with assistive technology).
Omit headers because the layout "feels obvious". Screen reader users can't navigate by visual cues.

Accessibility

Native table semantics carry most of the load: headers associate with cells, reading order matches visual order. The app owns column and row header scope, caption or labelled-by when the table needs explanation, and reading-order checks for any rearranged visual layout. See Accessibility for the full contract and testing notes.

Data table for sort, filter, selection, pagination, and async data.
Scrollable for wide or tall table containers.
Virtualized list for large flat datasets that don't need row-column semantics.
Typography for emphasis inside cells.

Tab Nav / Accessibility

Table / API and Development

Overview

When to use

For small, static datasets that don't need interactivity

For documentation-style comparisons

For custom layouts where you will implement any behavior yourself

When not to use

For any interactive data feature

For responsive cards that replace the table on mobile

For very large dynamic lists

Overview

Incident ID	Priority	Caller
PSA-24-001	P1	Morgan Reyes
PSA-24-002	P2	Dana Ortiz
PSA-24-003	P3	Jesse Parks

When to use

For small, static datasets that don't need interactivity

On the order of dozens of rows or fewer, where sort and filter are not meaningful. Reference matrices, comparison grids, and settings recaps fit here.

For documentation-style comparisons

Component prop reference tables, token recipes, feature matrices. The content is authored, not fetched—and the mental model is "read this grid", not "drive this grid".

For custom layouts where you will implement any behavior yourself

When none of DataTable's features apply and you only need the accessible HTML structure.

When not to use

For any interactive data feature

Sort, filter, search, pagination, row selection, row expansion, async loading, column resizing. Use DataTable. Re-implementing those on top of Table is expensive and error-prone.

For responsive cards that replace the table on mobile

For very large dynamic lists

Virtualize the data with VirtualizedList or graduate to DataTable. A flat Table with thousands of rows will crater layout performance.

Variants

Concern	Purpose	Emphasis
Column headers vs. data cells	Semantics	Always use proper header cells for columns
Row headers	Row identity	First cell as row header when it names the row
Alignment	Readability	Text left, numerics right, status icons centered
Scrollable wrapper	Overflow	Pair with `Scrollable` for wide or tall tables
Density	Spacing	Default for most content; tighter density for reference matrices

Composition

Content guidelines

Headers. Short, unique per column; sentence case per form label rules unless the table is documentation-heavy title casing.
Cells. Simple content. Use Text tokens for emphasis rather than ad-hoc styles.
Empty tables. Explain why empty and what to do next ("No entries yet. Add one from the settings panel."). Empty tables without context feel broken.
Internationalization. Watch alignment for RTL languages; test the longest expected column headers inside the target width.
Consistent formatting. Numbers, dates, and currency use the same format within a column. Switching formats mid-column taxes scanning.

Behavior and states

Non-interactive by default. Static tables have no built-in interaction states; if rows become clickable, use Interactable or row-level buttons with clear semantics. Avoid nesting conflicting controls.
Hover. Optional on rows; never rely on hover alone for essential information (touch users will miss it).
Selection, sort, filter. Not available—graduate to DataTable.

Best practices

Keep column order stable across loads. Operators scan by position, and shifting columns breaks muscle memory.
Use consistent number formatting within a column. Mix dollars and cents, or thousands and millions, only when the axis itself is the unit—and label it.
Limit column count. Horizontal scroll is acceptable but should not hide critical identifiers (the first column stays pinned conceptually even when the markup does not).
Use headers for every column and row-level headers where rows have a natural name (incident id, agency name).

Don't

Use Table because the layout "looks grid-like" for non-tabular content. Use CSS Grid or FlexBox.
Put complex forms inside cells without careful focus management. Inline edits are a DataTable feature; in a static Table, open a modal or drawer for the editing surface.
Merge cells in ways that confuse header associations unless the structure truly calls for it (and, when it does, explicitly test with assistive technology).
Omit headers because the layout "feels obvious". Screen reader users can't navigate by visual cues.