Tables

Do not use tables for layout. Use CSS to define page structure. Screen readers will read page content in the order that it is presented (e.g. top to bottom, left to right), so if this is not the order that the user is expected to consume the information, those relying on assistive technology will have difficulty comprehending.

Let the browser window determine the width of the table whenever possible, to reduce the horizontal scrolling required of those with low vision.

A flat, simple data structure will help keep the content comprehensible when a table is read by a screen reader. When a table layout is called for, keep in mind how the data will be perceived when heard and ensure that the context is always clear.

When proper HTML markup is in place, users of screen readers can navigate through tables one cell at a time, and they will hear the column and row headers spoken to them.

Unsighted users rely on clear labels and well defined structure in order to understand the purpose of a table and the information provided within.

Complex tables with two or more levels of headings and/or spanned cells introduce even more complexity, and require even more definition to ensure that associations between headings and cell data are preserved. For this reason, they should be avoided unless absolutely necessary.

If there are conditions where some rows or columns are hidden or not present in the DOM (i.e. there are widgets on the page for hiding rows or columns), the following properties are applied:

• aria-colcount or aria-rowcount is set to the total number of columns or rows, respectively.
• aria-colindex or aria-rowindex is set to the position of a cell within a row or column, respectively.

‍

Overview of Structural Markup

A caption identifies the overall topic of a table and is useful in most situations.

A summary provides orientation or navigation hints in complex tables.

Tables with one header for rows or columns are easy to distinguish. Mark up header cells with <th> and data cells with <td> elements.

Tables with two headers have a simple row header and a simple column header. For tables with unclear header directions, define the direction of each header by setting the scope attribute to col or row.

Tables with irregular headers have header cells that span multiple columns and/or rows. For these tables, define column and row groups and set the range of the header cells using the colgroup and rowgroup values of the scope attribute.

‍

Roles, States and Properties

The table container has role table.

If there is an element that serves as a label for the table, aria-labelledby is set on the table element with a value that refers to the labeling element. Otherwise, a label is specified for the table element using aria-label.

If the table has a caption or description, aria-describedby is set on the table element with a value referring to the element containing the description.

Use the <caption> element to summarize the contents of the table. This serves the same purpose as a label or a header without the user having to set the focus outside the table in order to understand context. The <caption> element must be the first thing after the opening tag.

• The caption element may be used whether or not the table includes a summary attribute. The caption element identifies the table whereas the summary attribute gives an overview of the purpose or explains how to navigate the table. If both are used, the summary should not duplicate information in the caption.

A table with fixed dimensions can cause problems for people who larger fonts or magnified screen views. The best practice is to let the browser window determine the width of the table whenever possible, to reduce the horizontal scrolling required of those with low vision. If cell widths need to be defined, use relative values, such a percentages, rather than pixel values.

Headers

Header cells must be marked up with <th>.

Using the “scope” attribute, within the column and row header tags (<th>), identifies whether a table header is a column header or a row header. It enables a screen reader to announce the associated column/row when reading the cell data, which removes the burden of remembering the order of presentation.

Scope will apply even if the table is complex with multiple levels of headers (such as in spanned cells). The scope of a table header will apply to all cells over which that header spans.

Designate row and/or column headers. In the markup, the <td> element is used for table data cells and the <th> element is used for table header cells.

Table headers should never be empty. This is particularly of concern for the top-left cell of some tables.

If the table contains sortable columns or rows, aria-sort is set to an appropriate value on the header cell element for the sorted column or row. This property indicates if items in a table or grid are sorted in ascending or descending order.

• Authors should only apply the aria-sort property to table headers or grid headers.
• If the property is not provided, there is no defined sort order.
• For each table or grid, authors should apply aria-sort to only one header at a time.

Rows

Each row container has role row and is either a DOM descendant of, or owned by, the table element or an element with role rowgroup.

The cell containing header information for a row in a grid has the role rowheader. Rowheader can be used as a row header in a table or grid. The rowheader establishes a relationship between it and all cells in the corresponding row. It is a structural equivalent to setting scope="row" on an HTML th element.

Authors must ensure elements with role rowheader are contained in, or owned by, an element with the role grid.

aria-rowcount defines the total number of rows in a table, grid, or treegrid.

Rows contain cell or gridcell elements, and thus serve to organize the table or grid. Authors must ensure elements with role row are contained in, or owned by, an element with the role table, grid, rowgroup, or treegrid.

In a treegrid, authors may mark rows as expandable, using the aria-expanded attribute to indicate the present status. This is not the case for an ordinary table or grid, in which the aria-expanded attribute is not present.

Applying the aria-selected state on a rowheader should not cause the user agent to automatically propagate the aria-selected state to all the cells in the corresponding row, although an author may choose to propagate selection in this manner depending on the specific application.

While the rowheader role can be used in both interactive grids and non-interactive tables, the use of aria-readonly and aria-required is only applicable to interactive elements. Therefore, authors should not use aria-required or aria-readonly in a rowheader that descends from a table, and user agents should not expose either property to assistive technologies unless the rowheader descends from a grid.

Columns

The role columnheader establishes a relationship between it and all cells in the corresponding column.

Authors must ensure elements with role columnheader are contained in, or owned by, an element with the role row.

aria-colcount defines the total number of columns in a table, grid, or treegrid.

Applying the aria-selected state on a columnheader should not cause the user agent to automatically propagate the aria-selected state to all the cells in the corresponding column, although an author may choose to propagate selection in this manner depending on the specific application.

While the columnheader role can be used in both interactive grids and non-interactive tables, the use of aria-readonly and aria-required is only applicable to interactive elements. Therefore, authors should not use aria-required or aria-readonly in a columnheader that descends from a table, and user agents should not expose either property to assistive technologies unless the columnheader descends from a grid.

Because cells are organized into rows, there is not a single container element for the column. The column is the set of gridcell elements in a particular position within their respective row containers.

Cells

Data cells must be marked up with <td>.

Each cell is either a DOM descendant of or owned by a row element and has one of the following roles:

• columnheader if the cell contains a title or header information for the column.
• rowheader if the cell contains title or header information for the row.
• cell if the cell does not contain column or row header information.

Defined cell heights should generally be avoided so the cell can expand downward to accommodate its content - something especially useful for users with low vision that may enlarge text content.

If the table includes cells that span multiple rows or multiple columns, then aria-rowspan or aria-colspan is applied.

‍