Table
Use tables to organize and display data.
Overview
Keyboard interaction
For sortable tables, the column headers are reachable by Tab and sortable with Space or Enter.
Controls inside tables
Any interactive controls in data cells are in the tab order and maintain normal keyboard operation. This also applies to expandable table rows, which operate in the same manner as accordions.
Labeling and updates
If columns are sortable, the sort symbols appear on hover or focus. A sorted column retains an indicator until it is no longer sorted.
Development considerations
Simple tables can have up to two rows of headers. Each header cell should have scope="col" or scope="row".
Complex tables have more than two levels of headers. Each header should have a unique id and each data cell should have a headers attribute with each related header cell’s id listed.
Add title and attribution in a caption. When adding a title, attribution, or a last-updated date to a table, include it in the <caption> tag inside of the <table> element.
Add an aria-live region to the page when enabling row sorting. An aria-live region immediately following the <table> element automatically announces when the sort state changes for visitors using screen readers, but it must be added to the HTML document before load: <div class="usa-sr-only usa-table__announcement-region" aria-live="polite"></div>
Don’t add aria-label attributes to sortable column headers. Enabling row sorting automatically adds aria-label attributes to the sortable column headers and their toggle sort buttons via JavaScript. These labels are updated to reflect each column’s current sort state (ascending, descending, or unsorted) whenever sort changes.
Scrollable tables need to be focusable. When you use the scrollable variant with a table, you must add the tabindex="0" attribute to the scrollable element. This attribute assures that users navigating with a keyboard are able to select and scroll the table. tabindex="0" enables focus on elements that do not get focus by default. This attribute does not change the tab order. It places the element in the logical navigation flow.