Table component documentation updates
Tables display tabular data in a basic grid comprised of cells, columns, and rows. This format makes it easy for users to scan large amounts of data.
Usage
- Display structured content, where each entry has the same attributes.
- Display a data set that will continue to grow (e.g. issues, user & environments)
- Let users review, enter, edit or filter granular data sets.
- Display a list of continuous, vertical indexes of text or images. Use Lists instead.
- Display contained content and actions on a single topic. Use Cards instead.
- Display hierarchical structures. Use the Tree view instead.
Basic table
The basic table is the default option for this component, however, additional functionality below can be added to refine the table for any use case.
To Do: Add Figma/Image Example
Search & filter
Any filtering controls that manipulate the data set (including clickable charts) should be placed directly above the table with the option to clear all data. See filter guidelines
To Do: Add Figma/Image Example
Sorting
Tables use column sorting rather than list sorting. The default sort direction of a table can be up or down depending on the use case and is indicated in the table header using an arrow icon. See sorting guidelines
To Do: Add Figma/Image Example
Pagination, lazy load & infinite scroll
Tables displaying data sets with more than 20 items should use either pagination, lazy load or infinite scroll. Tables have embedded pagination controls which are located at the bottom of the table. See pagination guidelines
To Do: Add Figma/Image Example
Inline actions
Table rows can include inline actions located n their far-right column. Inline actions should be visible at all times rather than showing on-hover. If there are two or more actions in a table row, consider using a button group or a “more menu” button with a dropdown list option.
To Do: Add Figma/Image Example
Expandable rows
Use expandable rows to progressively reveal more information about an item in a dataset. Do not use expandable rows to display hierarchical structures. Use the Tree view instead.
To Do: Add Figma Example
Styles
Default
To Do: Add Figma/Image Example
Zebra stripes 🦓
Alternating grey and white stripes can be used to help differentiate rows.
To Do: Add Figma/Image Example
Content
Headers
Always use column and/or row headers unless the table content is self-descriptive. Headers should be short, descriptive, and relevant. Avoid headers that are too long for the content in the rows below, and use title-case.
Columns
Columns should be ordered by priority or in a way that tells a story with the data. Size columns according to the data they contain rather than making them all an even width.
Rows
Rows can have a mix of interactive, read-only and editable cells.
Text alignment
Left-align text content rather than justifying or centering it. Right-align numeric data with a consistent number of decimal places to improve scannability.
Null values
If the data for a cell is null, blank or unavailable, you can either:
- Keep the cell empty to reduce noise and help with legibility
- Use a dash ("-") to signify missing data
Truncation
You can truncate long text strings with an ellipsis (“…”). On hover, the truncated text should display a tooltip including the full text. See tooltips guidelines
Empty state
A table’s empty state displays when there is no data, yet. See empty states guidelines.
Responsiveness
Tables work across multiple screen sizes and conform to responsive guidelines. Prevent horizontal scrolling to ensure the table doesn’t break the layout.
To Do: Add Figma/Image Example
Accessibility
Use proper semantic markup, so that users of screen readers can navigate through the table one cell at a time, hearing column and row headers spoken to them.
-
<th>
should not contain heading elements. -
<th>
should be descriptive and relevant. -
<th>
should have a definedscope
attribute to establish relationships between the table headings and rows/columns; for example,<th scope="col">
. -
<caption>
should be used to provide a title for a table. -
<caption>
should be an immediate child element of<table>
.
Design specifications
Color, spacing, dimension, and layout specific information about this component can be viewed using the following link: