data table

A data table holds a list that people work through: they scan it, sort it, select rows and act on them, often with the keyboard alone.

when to use

• For a list people work through: they scan it, sort it, select rows and act on them. It is the heart of a worklist.
• When rows need any of these: sorting by a column, selecting one row or many, grouping under a heading row, loading more rows a page at a time, or moving from row to row with the keyboard.
• For long lists. Shown a page at a time, it stays quick with thousands of rows; the React page has the details.

when to use something else

• For a short list of records that people only read. Use the plain table. It is simpler, and a screen reader has less to announce.
• For the details of one record. A single row with many columns is hard to read. List the labels and values in a card instead.
• For places to go. A set of apps or areas to open is a tile group, or the home page.
• To pick values in a form. Use checkboxes or a multi select. Selecting rows is for acting on them, not for filling in a form.
• When every column has to stay a column, however narrow the screen. The data table never scrolls sideways; it moves less important columns under each row instead. The plain table keeps all its columns and scrolls inside its frame.

anatomy

1. Frame. A thin border around the whole table, as wide as its container. The table never scrolls sideways, so its header can stick to the top of the page.
2. Header row. A short label for each column, on one line. It stays at the top while the rows scroll underneath, as a sticky header.
3. Sort button. In a column that can be sorted, the label is a button with a small double arrow beside it. The direction the column is sorted in is drawn in full, the other one faded.
4. Selection column. A narrow column of checkboxes: one in the header for every visible row, and one in each row.
5. Group row. A heading row across the whole table for the rows of one group. It holds an arrow that shows whether the group is open, the group's name, and an action for the group at its end.
6. Data row. The cells of one item, with a thin rule below. A row lightens under the pointer; a selected row is tinted blue and has a blue bar on its leading edge.
7. Row header. The cell that names the row, usually the first one, in brighter text.
8. Highlight. A bar in a state's colour on the leading edge of a row, for the few rows that need acting on. On a selected row it takes the place of the blue bar.
9. Pop-ins. On a narrow table, the labels and values of the columns that made room, under the row's name.
10. Empty cell. When there are no rows, one cell across the whole table holds the empty state.
11. Show more. Under a long list: how many rows are shown out of how many, and a small button to show the next page.
12. Progress line. While the table loads, a thin blue line moves along its top edge.

variants and states

sorting

People sort the table by clicking a column's label. Clicking the sorted column again turns the order around. Clicking another column sorts by that one, in its first direction: ascending, unless the column starts with the newest or largest first, as date columns usually do. There is no third click back to the unsorted order.

The sort is predictable. Rows that are equal keep the order they had. Text is compared the way people read it, so “E2” comes before “E10”, and capitals and accents make no difference. Dates are compared by time, and empty values always go last, whichever the direction.

In a grouped table, the rows stay in their groups, and the groups follow the order of their first row after sorting.

selection

When rows can be selected, the table gets a column of checkboxes. When to offer selection, and how a selection meets the actions above it, is described in selection and bulk actions. This is what the table itself does:

• People select a row with its checkbox, by clicking the row (unless clicking opens it), or with space on the row that has focus. shift selects a range, and ctrl + a (or cmd + a) selects every visible row. Behaviour, below, has the details.
• The checkbox in the header stands for every visible row: the rows on the screen, not those inside closed groups or beyond “show more”. It is ticked when every visible row that can be selected is selected, and shows the mixed state when only some of them are. Pressing it while it is ticked clears the whole selection, hidden rows included. It is disabled when no visible row can be selected. Offering “select all 2,500” is the job of the selection toolbar, not of this checkbox.
• A row that can't be selected has a disabled checkbox, and clicks, ranges, select-all and the keyboard all leave it out. Its status says why; see rows that can't be selected.

grouping

Rows that belong together can sit under a group row. Its label says what the group is and how many rows it holds, such as “The Quiet Harbour · S04 · 8 missing”, and keeps the name's own capitals.

A group row can carry one action at its end, a small quiet button that acts on the whole group, such as “grab all 8”. Pressing that button doesn't open or close the group.

A group opens and closes with a click on its row, with enter or space, or with the left and right arrow keys.

showing more

A long list doesn't have to arrive all at once. The table can show one page of rows, say 100, with a “show 100 more” button underneath that adds as many again. For the last few rows it says how many are left, such as “show 37 more”, and once everything is shown, the button goes.

Beside the button, a count such as “100 of 2,500” says how many rows are shown, out of how many there are. A screen reader announces each new count.

Only data rows on the screen count as shown; group rows don't count at all. Rows inside a closed group count in the total but never as shown, so with groups closed the count can stop below the total, such as “2,380 of 2,500”, with no button left.

The number of rows shown only grows, until the view changes: a new filter or another tab can start it again at one page.