table

A table sets out a short list of records in rows and columns, so people can read them and compare the values down a column. It only shows the rows: for sorting, selecting or moving between rows with the keyboard, use the data table.

when to use

• To show a short set of records that people only read, all with the same fields, so they can compare the values down a column: workloads, volumes, recent runs.
• When every row fits on the screen, and nobody needs to sort the rows, select them or act on them.
• As the body of a panel, in a card with no padding inside, so the table meets the card's frame.

when to use something else

• For a list people work through. When people sort it, select rows, group them, load more or move between rows with the keyboard, use the data table. This table has none of that, and adding it on top is how support for the keyboard and for screen readers gets lost.
• For a screen whose job is to find items and act on them. That is a worklist: a filter bar, a data table and a toolbar.
• For layout. A table tells a screen reader that it holds rows and columns, which means nothing for a form. Lay a form out with a stack instead; forms and settings shows how.
• For the details of one record. A single row with many columns is hard to read, and it scrolls sideways. List the labels and values in a card instead.

anatomy

1. Frame. A thin border around the whole table, as wide as its container. A table wider than its frame scrolls sideways inside it.
2. Header row. A short label for each column, in small monospace and lowercase, on a slightly darker background. A label never wraps onto a second line.
3. Body row. One record. Its cells lighten under the pointer. Rows aren't striped: every row has the same background, and a hairline under each one keeps them apart. The last row has no line of its own; the frame closes the table.
4. Cell. One value, in monospace, with room around it, centred from top to bottom.
5. Empty row. When there are no rows, one cell across the whole table says so, in small, dim, centred text.

variants and states

dense

A dense table has less space around each cell, so more rows fit on the screen: useful for long lists and side panels. More on density is in layout.

cells with more than text

A cell can hold more than text. Tags go in as badges. The state of the record goes in as a status, never as a coloured badge.

empty

With no rows, a single row says so. It reads “no rows” until you give it the table's own words; see content, below.

wider than its frame

A table wider than its container scrolls sideways inside its frame. The page itself doesn't scroll sideways.

built from its parts

Some tables need more than plain columns: a header over two columns, a row header, a cell that spans several rows or columns. Such a table is built from the table's parts, and it looks the same.

behaviour

• The table itself takes no focus; what you put in its cells does. tab moves through the links and buttons in the cells, in reading order.
• Rows lighten under the pointer, but a click on a row does nothing. There is no row selection, no row action and no sorting.
• While a table is wider than its frame, the frame becomes a tab stop of its own: tab reaches it, and the left and right arrow keys scroll it sideways.

The full keyboard map is on the table's React page.

accessibility

• Underneath, the table is a real table, so a screen reader's own table commands work: people can move by cell, by row and by column, and hear each cell with the label of its column.
• Name every table, with the heading above it or with a label of its own.
• Write the column labels as they should be read. The lowercase look is only a style; a screen reader reads the text as you wrote it.
• Say a state in words, with a status. Colour in a cell is never announced.
• A frame that scrolls gets the same name as its table, and shows the focus outline while it has focus. Where you can, keep a table narrow enough to fit, and put the columns that matter first.
• A row header, a first cell that names its row, needs the table built from its parts.
• Changes to the rows are not announced. When rows change because of something the person did, say what happened; message handling shows how.

Today: a row header takes the look of a column label, in small, muted monospace with the same spacing, and in the last row it keeps the line under it.

content

• Column labels. A noun of one or two words, lowercase: “workload”, “size”, “last run”. Put the unit in the label, “cpu (cores)”, rather than in every cell.
• Numbers. Align them to the right, and give them the same number of decimals down a column, so the digits line up.
• Empty. Say what is missing, in the table's own words: “no workloads in this project”, not “no data”.
• A failed load. It is not an empty table. Show the error in a banner above it. When an empty table needs an explanation or a next step, see empty states.

do and don't

related

• Data table: the table people work through, with sorting, selection, groups, more rows on demand and the keyboard.
• Card: the frame a table usually sits in, with no padding inside.
• Status: the state of a record, inside a cell.
• Empty states: when one line in an empty row isn't enough.

specs