Table

Reported as: Table has multiple footers

A table must place all its footer rows in a single <tfoot> element.

When a table has more than one <tfoot>, browsers don't handle the extras consistently, and the reading order can change. Screen reader users may hear totals or summary rows in the wrong place, or be unable to tell them from ordinary data.

Move every footer row into one <tfoot>.

Severity: Moderate

Reported as: Table has multiple headers

A table should place all its header rows in a single <thead> element.

When a table has more than one <thead>, browsers treat the extras as body sections. Screen reader users may then hear header rows as data, or hear a header twice.

Move every header row into one <thead>. A single <thead> can hold several header rows.

Severity: Minor

Reported as: No group members with required role

A table must contain at least one row, directly or inside a row group.

When a table has no descendants with the row role, screen reader users hear that a table is there but find nothing to read, and they can't tell whether the data failed to load or doesn't exist.

Render the table only when it has rows, and show a message outside it when there's no data. In a custom table, give each row role="row".

Severity: Serious

Reported as: No group members with required role

A table's row group must contain at least one element with the row role.

When a <thead>, <tbody>, <tfoot>, or role="rowgroup" element has no rows, screen reader users moving by section reach a group with nothing in it and can't tell whether content failed to load.

Render a row group only when it has rows, and make sure each row inside it is a <tr> or carries role="row".

Severity: Serious

Reported as: No group members with required role

A table row must contain at least one cell with the cell, columnheader, or rowheader role.

When a row has no cells, or its children are generic elements, screen reader users moving through the table reach a row with nothing in it, and its columns no longer line up with the rows around it.

Put a <td> or <th> in every row, or give each cell in a custom row the cell, columnheader, or rowheader role.

Severity: Serious

Reported as: Complex headers in ARIA table

A table with header cells that span rows or columns should be built with native table elements.

When a custom table sets aria-colspan or aria-rowspan on its headers, some screen readers don't associate the spanning header with the cells beneath it, even inside a row group. Users then hear data without the header that explains it.

Use a native <table>, with colspan or rowspan and scope on each spanning <th>, so the browser can apply its own header association. If the table has to be a custom table, don't rely on aria-colspan and aria-rowspan alone. Point each cell's aria-describedby at the spanning header as well.

Severity: Serious

Reported as: Conflicting scope spanning values

A header cell that spans several columns or rows must declare that it heads the group.

When a <th> with colspan has scope="col", or one with rowspan has scope="row", it claims to head a single column or row. Screen reader users then hear it with the wrong cells, or miss it on some of the cells it labels.

Set scope="colgroup" on a header with colspan, and scope="rowgroup" on a header with rowspan.

Severity: Serious

Reported as: Missing table headers

A data table must have header cells that identify what each column or row holds.

When a table has no <th> elements and no elements with role="columnheader" or role="rowheader", screen reader users hear values with nothing to say what they mean.

Mark the cells that label columns or rows as header cells: <th> in a native table, or role="columnheader" and role="rowheader" in a custom table. If the table is there only for layout, replace it with CSS layout.

Severity: Moderate

Reported as: Table headers missing scope attribute

Each <th> in a table must declare with scope whether it labels a column or a row.

When scope is missing, browsers guess the association from the table's layout, and different browsers can guess differently. Screen reader users may then hear the wrong header for a cell, or none.

Add scope="col" or scope="row" to every <th>, or scope="colgroup" or scope="rowgroup" to a spanning header.

Severity: Moderate

Reported as: Element has incorrect role

Each part of a table must expose the role that matches its position in the structure.

When a part carries the wrong role, or none, assistive technologies misreport the table. When a header is exposed as a cell, screen reader users don't hear it with the data it labels, and a row exposed as a generic element breaks their navigation by row and column.

Use native table elements, or set each role from the mapping in Custom ARIA Table.

Severity: Critical

Reported as: Incorrect root element

A table's table role should sit on the outermost element that contains its rows.

When the role is set on a descendant rather than on the container, the container isn't identified as a table, and rows outside the element carrying the role can fall outside the structure assistive technologies present. Screen reader users then don't reach those rows as part of the table.

Move role="table" to the element that contains every row, or use a native <table> as the container.

Reported as: Accessible name

A table cell must have an accessible name that conveys its content.

When a cell holds only an icon or image with no text alternative, screen reader users hear an empty cell. If it's a header cell, every data cell it labels loses its context too.

Give an image in the cell alt text, or add visually hidden text to the cell. Say what the icon means, such as "Available" rather than "Check mark".

Severity: Moderate

Reported as: Missing contextual labeling

A table, native or custom, must have an accessible name that identifies the data it holds.

When a table has no name from any source, screen reader users hear only that they've entered a table, with no clue which one or what it's for. On a page with several tables, every one is listed the same way.

Give the table a name with a <caption>, or with aria-labelledby pointing at the visible heading or caption that introduces it. Use aria-label only when there's no visible text to reference.

Severity: Moderate

Reported as: Table missing accessible name

A native <table> should carry a <caption> that says what it holds, or an accessible name set with ARIA.

When only the prose or heading above the table identifies it, users who reach it by jumping from table to table find an unnamed entry and have to read its headers to learn what it holds.

Add a <caption> as the first child of the <table>. If a <caption> can't be used, give the table an accessible name by setting aria-labelledby to reference visible text, or by setting aria-label.

Severity: Moderate

Reported as: Table has empty caption

A table's caption should hold text that identifies the table, or not be there at all.

When the caption is empty or holds only whitespace, the table gets an empty accessible name. Screen reader users get no indication of what the table holds, even though the markup looks as if it names the table.

Write a short phrase in the caption that says what the table holds. If you don't want a caption, remove the element and name the table with aria-labelledby or aria-label. In a template, render the caption only when there's text for it.

Severity: Moderate

Reported as: Missing aria-colindex

When a table declares aria-colcount, each of its rows or each of its cells must declare a column position with aria-colindex.

When the positions are missing, assistive technologies know how many columns the table has but not which of them are rendered, so screen reader users hear the wrong column position for each cell.

Add aria-colindex to every row when the rendered columns are consecutive, or to every cell when they're not. Use the same level throughout the table.

Severity: Serious

Reported as: Aria-colcount incorrect value

A table's aria-colcount must count every column in its data, including columns that aren't rendered.

When the value is lower than the number of cells already rendered in a row, the table contradicts itself, and screen reader users are told the table is narrower than what they can reach.

Set aria-colcount to the total number of columns. If the total isn't known, set it to -1.

Severity: Moderate

Reported as: Aria-rowcount incorrect value

A table's aria-rowcount must count every row in its data, including header rows and rows that aren't rendered.

When the value is lower than the number of rows already rendered, screen reader users are told the table has fewer rows than they can reach, and the positions they hear stop making sense.

Set aria-rowcount to the total number of rows. If the total isn't known, set it to -1.

Severity: Moderate

Reported as: Aria-colindex with no aria-colcount context

A table that uses aria-colindex should declare its total number of columns with aria-colcount.

When the table has no aria-colcount, a column position has nothing to count against, so screen reader users hear a position without learning how wide the table is.

Add aria-colcount to the table element, set to the total number of columns, or -1 if the total isn't known.

Severity: Minor

Reported as: Aria-rowindex with no aria-rowcount context

A table that uses aria-rowindex should declare its total number of rows with aria-rowcount.

When the table has no aria-rowcount, a row position has nothing to count against, so screen reader users hear a position without learning how long the table is.

Add aria-rowcount to the table element, set to the total number of rows, or -1 if the total isn't known.

Severity: Minor

Reported as: Inconsistent index values

A table's row and column indexes should be set on every rendered row or cell, with values that increase in order.

When some rows or cells carry an index and others don't, or a value repeats or goes backward, assistive technologies can't work out where a cell sits. Screen reader users then hear wrong positions or find table-reading commands skipping rows.

Set the index on every rendered row, or on every cell, with each value greater than the one before. A jump in the numbers is fine when the rows or columns between them aren't rendered.

Severity: Minor

Reported as: Index out of range

A table's aria-rowindex and aria-colindex values should not exceed the totals set in aria-rowcount and aria-colcount.

When an index is higher than its total, screen reader users hear an impossible position, such as row 60 of 50.

Update the count when the data grows, and derive each index from the same data that sets the count.

Severity: Minor

Reported as: Mixed aria-colindex implementation

A table must declare column positions with aria-colindex on its rows or on its cells, not on both.

When both levels carry aria-colindex, assistive technologies get two conflicting sources of column position, and screen reader users hear the wrong column for some cells.

Set aria-colindex on each row when the rendered columns are consecutive, or on each cell when they're not, and remove it from the other level.

Severity: Minor

Reported as: Negative row or column index

A table's aria-rowindex and aria-colindex values should be positive whole numbers, starting at 1.

When a value is zero or negative, assistive technologies ignore it or misreport it, and screen reader users hear a wrong position for the cell or none at all.

Number rows and columns from 1. If your data uses zero-based indexes, add 1 to each.

Severity: Minor

Reported as: Component does not support disabled state

A table must declare a disabled state only on the controls inside its cells, not on the table, its row groups, rows, or cells.

When a table or one of its parts carries aria-disabled, assistive technologies ignore it or report a state users can't act on. Users may then think a row is unavailable when nothing in it has changed.

Remove the attribute, and disable the control inside the cell instead.

Severity: Serious

Reported as: Element type does not support disabled state

An element in a table must carry disabled or aria-disabled only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute, as the section intro describes. When a control inside the table is unavailable, set the disabled state on that control, using an element or role that supports it.

Severity: Serious

Reported as: Conflicting disabled values

A control in a table must have a single, consistent disabled state.

When an element carries both disabled and aria-disabled with contradictory values, such as disabled alongside aria-disabled="false", assistive technologies can report a different state than the browser enforces. Screen reader users then can't tell whether the control can be used.

Use one mechanism: disabled alone on a native form control, or aria-disabled alone on a custom one.

Severity: Serious

Reported as: Element does not support the disabled attribute

A table's parts must not carry the HTML disabled attribute.

When disabled is set on a <table>, <tr>, <th>, or <td>, or on an element with a table role, browsers ignore it. The controls inside stay operable, and screen reader users hear nothing about the part being unavailable even if it looks disabled.

Remove the attribute, and set disabled on the form control inside the cell instead.

Severity: Serious

Reported as: Unsupported table structure

A table cell should hold content rather than another table.

When a table is nested in a cell, assistive technologies present the inner table as a separate table with its own rows and columns. Users then have to keep track of two sets of headers and positions at once, and can easily lose their place.

Move the data into the outer table, or place the inner table beside it rather than inside it. Use CSS if you need to arrange content within a cell.

Reported as: Avoid aria-owns

A table and its row groups should hold their rows in the DOM rather than own them with aria-owns.

When rows rendered elsewhere are owned, assistive technology places them after the table's own rows, wherever they appear on screen. Assistive technology that doesn't honor the attribute reports them outside the table. Screen reader users then hear rows out of sequence, or find rows that aren't counted or reachable with table navigation.

Render the rows inside the table or its row groups, using a virtualization library that renders rows in place, or portal the whole table. When some rows must be owned, list every row in aria-owns in the order users should meet them.

Reported as: Invalid aria-owns values

When a table uses aria-owns, each element it references should have the row or rowgroup role, and a row group should reference only rows.

When an owned element has another role, the table's structure no longer adds up. Row counts and positions come out wrong, and screen reader users hear a garbled or incomplete table. An element owned by two containers, or two containers that own each other, leaves the structure undefined.

Reference only rows and row groups, and own each element from one container. Better still, move them into the table in the DOM and remove aria-owns.

Reported as: Table sort not accessible to keyboard

A sortable header must let keyboard users reach and operate its sort control.

When sorting responds only to a pointer click on the header, keyboard users can't change the table's order.

Put a <button> inside the header cell and run the sort from its click event, which also fires for Enter and Space. Keep aria-sort on the header cell, not on the button.

Severity: Serious

Reported as: Ambiguous mult-sort levels

A table must declare an active sort on no more than one header at a time.

When more than one header carries aria-sort set to ascending, descending, or other, screen reader users can't tell which column decides the order. ARIA has no way to express sort priority across several columns.

Set an active aria-sort value on the header of the primary sort column only. Remove the attribute from the other headers, or set it to none.

Severity: Minor

Reported as: Aria-sort invalid value

A header's aria-sort value must be one of the four the property defines: ascending, descending, other, or none.

When the value is misspelled or made up, assistive technologies ignore it, and users get no sort information for that header.

Use ascending or descending for those orders, other for any other sort algorithm, and none, or no attribute, for an unsorted header.

Severity: Minor

Reported as: Aria-sort on a table cell

A table should declare its sort order on the header cell of the sorted column or row.

When aria-sort is on a data cell, it has no defined meaning, and assistive technologies ignore it or handle it unpredictably. Screen reader users then don't learn how the table is sorted.

Move aria-sort to the <th>, or the element with role="columnheader" or role="rowheader", that heads the sorted column or row.

Severity: Minor

Reported as: Deprecated keypress listener

A table's key handling should use keydown or keyup, not keypress.

When a handler listens for keypress, keys the browser doesn't send through that event go unanswered, and keyboard users find the table ignoring keys it's meant to respond to.

Replace each keypress listener with a keydown listener, and read the key from event.key.

Severity: Minor

Most relate to 1.3.1 Info and Relationships: naming the table, rows in the table and its row groups, cells in each row, header cells with a scope that matches their span, spanning headers built natively, a single sorted column, and the row and column counts and indexes.

The roles of the table's parts, each cell's name, a valid aria-sort value, and how a disabled state is declared relate to 4.1.2 Name, Role, Value.

Sorting from the keyboard relates to 2.1.1 Keyboard, and a single footer section to 1.3.2 Meaningful Sequence.

A single header section, a caption with text, a caption on a native table, aria-sort on a header, and indexes that come with a total, run in order, stay in range, and start at 1 map to no WCAG success criterion and are best practices.

Severity reflects how much an issue gets in users' way. Critical issues stop users outright, and a part of the table with the wrong role, or none, is the one critical issue.

Serious issues confuse users though tasks are still possible:

• A table, row group, or row with nothing in it
• Spanning headers that aren't associated with their cells
• A sort control keyboard users can't reach
• Missing column indexes
• A wrong disabled state

Moderate issues make the table harder to read or use:

• More than one footer section
• Missing header cells, or a missing scope
• A table with no name, or an empty or missing caption
• A cell with no accessible name
• Row or column totals that can't be true

Minor issues are smaller inconsistencies in the markup:

• More than one header section
• An ambiguous, invalid, or misplaced aria-sort
• Indexes without a total, out of order, out of range, set in two places, or below 1

The aria-owns checks and the checks on where the table role sits and on nested tables carry no severity: Evinced reports them as general and sanity checks.