Table

When to use

Table shows a short, read-only data set in rows and columns: the records on a detail page, a comparison, a summary. All the data is already on screen when the page loads and users only read it.

When not to use

• When you need sorting, filtering, pagination or selection: use DataTable. DataTable uses the same parts as Table; the difference is behaviour, not looks.
• For key-value pairs: use DescriptionList; it gives a semantic definition list instead of a two-column table.
• For repeated single-column rows: use ListItem.
• For layout only: use Grid and Stack; a table is for data, not for layout.

Table or DataTable

	Table	DataTable
Data	Small, read-only, ready on the page	Large, fetched or changing
Interaction	None; scrolling only	Sorting, filtering, pagination, selection
State	None	Row selection, column layout
Parts	Table.*	The same Table.* parts

Anatomy

1. Scroll region (root): the named, focusable div that wraps the table.
2. Caption (caption): names the table; visible or hidden.
3. Header (Table.Header): the row with the column headers (Table.HeaderCell).
4. Body (Table.Body): the data rows (Table.Row), the row header (Table.RowHeader) and cells (Table.Cell).
5. Footer (Table.Footer): summary rows such as totals.

Behaviour

• A Table is static: rows are not clickable and the table does not sort. Use DataTable when you need interaction.
• When the table is wider or taller than its container, the scroll region scrolls. The region is named and takes focus with Tab.
• stickyHeader keeps the header cells at the top of the container; you must give the container a height.
• hoverable changes colour only; a row never lifts.
• A selected row is selected visually only; aria-selected is not used on a plain table.
• Long text is cut on one line with truncate; the column needs a width.

Guidelines

Give every table a caption

caption is required. It names the table for screen readers and is the name of the scroll region.

Item list

Name	Status
First item	Active

DoThere is a caption; hide it visually if needed.

A table without a caption cannot be built with this component.

Don'tNo visible caption or name: it reads like a layout table.

Align numbers to the end

Use numeric for numeric columns: digits line up and can be compared.

Item list

Name	Count
First item	1,240
Second item	86

DoNumbers aligned to the end, with tabular numerals.

Item list

Name	Count
First item	1,240
Second item	86

Don'tNumbers aligned to the start: the digits do not line up.

Name the row

Make the first cell a Table.RowHeader; screen readers read each cell together with the row’s name.

Item list

Name	Owner
First item	Alex

DoThe first cell is a row header.

Item list

Name	Owner
First item	Alex

Don'tThe first cell is an ordinary cell: the row has no name.

Show status in text

Use Badge or StatusBadge for a status in a cell; do not leave it to the background colour alone.

Item list

First item	Active

DoThe status is in a Badge, as text.

Item list

First item

Don'tOnly the selected background says something about the row.

Content

• Keep column headers short and in sentence case: “Created”, “Owner”. Do not force upper case; case conversion can produce the wrong letter in Turkish.
• Write the caption as a noun phrase: “Item list”.
• Do not leave a meaningful cell empty; write “None” or “-”.
• Format dates and numbers the same way within a column.

Related components

• DataTable: for data that needs sorting, filtering, pagination and selection; it uses the same parts.
• Badge: for a status in a cell.
• StatusBadge: for a status from the fixed vocabulary.
• DescriptionList: for key-value pairs.