DataTable

DataTable is a 2-dimensional data structure where each row is an item, and each column is a data point about the item.

Page navigation navigation

Labeling and describing the table

The table must have a title, and can optionally have a subtitle to describe more context. If you encounter a case where there is enough context that the table doesn’t need a visible label, you may hide it so it’s only accessible to assistive technologies.

If you use the table header, the table's title and subtitle will automatically be associated with the table for assistive technologies.

If your table's title exists somewhere else on the page (for example, in the PageHeader), then you must manually associate that contextual information with the table using ARIA.

Labeling actions

The row header string will be prepended to the ARIA text of action buttons. For example, Download "{row header}", "Actions: {row header}"

To handle cases where the row header can be very long, we should give consumers the option to specify a shorter string to identify the rows. For example, if an issue title is used as the row header, we could use the issue number instead of the full issue title.

Pagination buttons

The pagination control for a DataTable uses button elements, and not a elements. This is because activating the pagination control requests data, and does not have a corresponding URL to link to.

Loading and sorting content

It is important to ensure parity between what can be seen visually when a table is loading or sorting content and what is announced to assistive technology. This is provided by the DataTable component automatically, but must be considered if a custom loading solution is otherwise utilized. For loading content via a custom loading method, this also includes the initial loading period. An announcement should not be made if content is retrieved before 750ms.