Table

A table shows data in columns and rows.
Status:
In use

Tables help logically organize information and group like things together, and they make it easier to understand complex content. They’re especially useful for showing long lists of sequential or structured content. Users read tables one row or column at a time, making it easy to digest and compare information.

Tables also help users find specific information within a large data set. 

Examples and code

NOTE: We don't use all of these, and I doubt we need all of them. 

  1. Standard table <-- NEED
  2. Striped table <-- NEED
    1. A striped table can improve readability by visually grouping row content with alternating background colors.
  3. Borderless table
    1. A borderless table can be useful when you want the information to feel more a part of the text it accompanies and extends.
  4. Scrollable table
    1. A scrollable table is ideal for dense data.
  5. Responsive stacked table
    1. A responsive stacked table collapses at narrow widths for better readability on small screens.
  6. Sticky table headers [would we use these?]
    1. Sticky table headers keep tabular data in context by sticking table headers to the top of the page as the user scrolls.

When to use

  • Displaying tabular data. When you need to display tabular information, such as statistical data.
  • Displaying directories. When listing locations or resources that have similarly structured content for many items.

When to consider something else 

  • Non-tabular data. Depending on the type of content, consider using other presentation formats, such as definition lists or hierarchical lists.
  • Robust data visualization. If you need to display more complex relationships or data visualizations, consider a bar graph, infographic, or other type of chart.
  • Dashboards and other layouts. Don’t use tables in place of a layout grid. Table content should follow a consistent structure using headers and logical columns and rows.
  • Long-form content. Table cell content should be brief and scannable. If you find yourself drafting multiple bullet points or paragraphs within a single table cell, the content is likely better off under conventional page headers or in an accordion.
  • Groups of items with different structures. Consider a list or cards for content items that don’t follow a consistent pattern.

Usability guidance

  • Keep it simple. Tables are great at displaying data and complex information. Minimal visual styling helps surface this information more easily.
  • Always use a header row. Use plain language and short labels to define the type of information that can be found in each column or row. For more complex table structures, review the WCAG accessibility recommendations for tables.
  • Predictably format columns. Take care not to vary units or formatting within the same column. Instead, normalize values so they can be easily compared. For example, if most of the rows in a table show a count in days, don’t have some rows that count by weeks.
  • Consider a small-screen experience. On mobile devices and other small screens, numerical data across many columns can be easier to understand if the table scrolls horizontally. Directory lists are more readable if the rows display in a stacked layout. For tables with more than two columns, make sure you choose either a scrollable or a stacked variant.
  • Minimize the number of columns. It’s easier for users to read down a long list of rows than it is to read across a long list of columns. Eliminate columns when possible, or consider swapping the columns and rows to improve scannability.
  • Enable sort where useful. Add row sorting to individual columns of long tables where the data can be logically ordered either alphabetically or numerically.
  • Don’t use row sorting with merged cells. Sorting won’t work properly if your table contains colspan or rowspan attributes on the cells.

Accessibility guidance - NEEDS REVIEW

  • 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 .usa-table-container--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.

 

 

Components

Utilities