Table

Represents tabular data in rows and columns ranging from basic usage to enhanced feature set for additional functionality.

Best Practices

1. In order to be well-formed and appear in the accessibility tree for assistive technology, a table requires the table head (<thead>) and table body (<tbody>) elements.

2. Every table cell requires a logical column header and/or row header.

3. Columns with string data should be left aligned, while columns with numeric data should be right aligned (vice versa for RTL).

4. A table accessibility may be enhanced by adding a <caption> to relay the subject of the table.

<div class="table" role="group" aria-label="Video games for sale" tabindex="0">
  <table>
    <caption>
      Video game consoles for sale.
    </caption>
    <thead>
      <tr>
        <th scope="col">Seller</th>
        <th scope="col">Item</th>
        <th scope="col">Image</th>
        <th scope="col" class="numeric">List Price</th>
        <th scope="col" class="numeric">Quantity Available</th>
        <th scope="col" class="numeric">Quantity Sold</th>
        <th scope="col" class="numeric">Watchers</th>
        <th scope="col" class="numeric">Protection</th>
        <th scope="col">Shipping</th>
        <th scope="col">Delivery</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td data-title="Seller">Nintendo</td>
        <td data-title="Item">Switch</td>
        <td data-title="Image"></td>
        <td class="numeric">$287.96</td>
        <td class="numeric">300</td>
        <td class="numeric">207</td>
        <td class="numeric">95</td>
        <td class="numeric">$17.99</td>
        <td>FREE</td>
        <td>4/1 - 4/5</td>
      </tr>
    </tbody>
  </table>
</div>

Do NOT use tables as a means for visual layout of page structure in rows and columns. Use CSS instead! See the Layout Tables Anti-Pattern for more information.

Sortable Table

A sortable table is a table that allows users to sort the data in the table by clicking on the column headers. You can make tables sortable by using sort buttons in thead > th . Additionally, for accessibility purposes, aria-sort="ascending" or aria-sort="descending" should be added respectively to the <th> to reflect the current sort order.

<div class="table" role="group" aria-label="Video games for sale" tabindex="0">
    <table>
        <thead>
            <tr>
                <th class="table-cell" aria-sort="descending">
                    <button type="button">
                        Seller
                        <svg aria-hidden="true" class="icon icon--12" height="28" width="28">
                            <use href="#icon-sort-down-12"></use>
                        </svg>
                    </button>
                </th>
                <th class="table-cell">
                    <button type="button">
                        Item
                        <svg aria-hidden="true" class="icon icon--12" height="28" width="28">
                            <use href="#icon-sort-12"></use>
                        </svg>
                    </button>
                </th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <th class="table-cell">Nintendo</th>
                <td class="table-cell">
                    <div class="table-cell__layout">
                        <div class="table-cell__thumbnail">
                            <img src="src/routes/static/img/tb-profile-pic.jpg" alt="Nintendo Switch" />
                        </div>
                        <div class="table-cell__multiline">
                            <div class="table-cell__data">
                                Nintendo Switch Brand New Gaming System with Four Controllers
                            </div>
                            <div class="table-cell__data table-cell__data--secondary">
                                SKU : A43BTR5678  •  Quantity : 1
                            </div>
                        </div>
                    </div>
                </td>
                <td class="table-cell">
                    <span class="signal signal--recent">Ready to Ship</span>
                </td>
            </tr>
        </tbody>
    </table>
</div>

Responsive Layouts

Responsive considerations should be made to ensure that tables are easily consumable and consistent across all screens.

1. Data Tables should continue to look like tables on all screens including smallest phone screens.

2. Data Tables should be fluid stretching to the width of the container.

3. Data Tables should span the full width of containers.

4. Data Tables should allow the columns to scroll horizontally inside the table only. The entire page body should not be scrolling horizontally.

5. Data Tables that have a sticky header with an infinite scroll and no pagination, should typically have a max-height less than the total height of the viewport to allow users to easily scroll past the table without having to exhaust the entire contents of the table before being allowed to scroll to the rest of the page.

Interaction Design

This section provides interaction design for keyboard, screen reader and pointing devices.

Keyboard

The top-level container element should have a tabindex="0"to make it focusable, an aria-label or aria-labeledby to relay context of the table, and should have a role="group" to make it accessible to screen readers. That will also allow the table elements to be scrollable inside the container, both vertically (when overflowing) and horizontally.

Tabbing order for interactive elements inside a table need to follow the natural sequencing of the elements as they appear row by row from top to bottom, and column by column per the respective RTL/LTR modes.

Sortable columns are achieved by adding a tri-state button (at rest, toggled sort descending, toggled sort ascending) as the contents of the table header cell. The three states would be cycled through on click/tap/keyboard as such: Rest > Sort Descending > Sort Ascending > Rest ...

The usual rules for button apply.

Screen Reader

1. Table must be listed in screen reader list of tables.

2. Screen reader must be navigable with screen reader table command. For example, in VoiceOver this command is VO+CMD+T.

3. Screen reader must announce value of every cell.

4. Screen reader must announce value of column header when instructed to do so. For example, in VoiceOver this command is VO+C.

5. Sortable column must be announced by screen reader.

6. Current sort state of sortable columns must be announce by screen reader.

7. When moving from column to column, screen reader announces new column scope. Typically this scope is the value of the column header.

8. When moving from row to row, screen reader announces new row scope. Typically this scope is the value of the row header.

Pointer

The only special consideration for table is sortable columns. Typically this is achieved by adding a toggle button as the contents of the table header cell. The usual rules for button apply.

ARIA Reference

aria-sort

Applied to column headings to convey descending or ascending sorted stated.