Table

View source on GitHub

​​A table is a set of structured data that is easy for a user to scan, examine, and compare. Table data is displayed in a grid format and can be used to structure both interactive and static data.

Props

Component props
Name
Type
Default
accessibilityLabel
Required
string
-

Label for screen readers to announce Table.

borderStyle
"sm" | "none"
"none"

Specify a border width for table: "sm" is 1px

children
React.Node
-
maxHeight
number | string
-

Use numbers for pixels: maxHeight={100} and strings for percentages: maxHeight="100%"

stickyColumns
number
-

Specify how many columns from the start of the Table should be sticky when scrolling horizontally. See the sticky column example for details.

Usage guidelines

When to Use
  • Displaying a set of structured data in a scannable way, that populates 2 or more rows.
  • Allowing users to compare information in rows and columns.
When Not to Use
  • There will never be enough data to populate at least 2 rows.
  • Displaying content that doesn’t follow a consistent pattern and can't be broken down into columns.
  • Providing robust data that doesn't fit in a tabular format. If there is a need to display a more complex data relationship, consider an info-graphic or a non-tabular format.

Best practices

Style

Do

Use accessible Gestalt grays for table text, and reserve colors to sparingly accent important status and information. Avoid over-styling text.

Don't

Overuse color and styling for text in tables; it can make it hard to scan for important status updates and crucial information.

Alignment

Do

Align content so that it’s easy to scan, read and compare:

  • Start-align text and combo-content (combinations of text, numbers and/or graphics)
  • End-align numbers only
  • Align headers with their corresponding content
  • Use tabular lining for numbers
Don't

Align content so that it makes it harder to scan, read, and compare.

  • Center-align content
  • Use proportional figures for numbers as they don’t quite align
  • End-align text and combo-content (combinations of text, numbers and/or graphics)
  • Misalign headers with their corresponding content
Do

Place unit type on a separate column so that amounts can still align and be compared.

Don't

Mix text and graphics with numbers that need to be compared with each other.

Content

Do

Make content digestible and scannable:

  • Keep headers clear and concise
  • Include an a visual indicator for cells that don’t have content.
  • Give enough space for content to account for localization.
  • Wrap important content to multiple lines
  • Truncate secondary information, especially if a user is going to get the full content upon click of a link in the table.
Don't

Add so much content that it’s hard for a user to read, examine and scan:

  • Don’t truncate content that a user needs to examine in relation to other content in the table.
  • Leave cells blank so that it isn’t clear if all data has loaded.
Do

Expand rows if the additional content is simple, doesn’t contain a lot of interaction and doesn’t take up more than 50% of the screen.

Don't

Use an expand to display dense, highly-interactive content. Use a new page or a Sheet for that.

Localization

Be sure to localize text and accessibilityLabel.

Note that localization can lengthen text by 20 to 30 percent; follow our guidelines on concise content and headings to account for localization.

Wrap important table content instead of truncating. Use truncation only for secondary content, and include a tooltip to show the full text on hover.

Accessibility

Labels

Use accessibilityLabel to properly announce the content of the table. For example, use "Campaign Status Information".

Don’t include the word “table” as part of the label to prevent redundancy: the VoiceOver already appends “table” to the label and the Category “Table” in the rotor already describes the nature of the component.

In terms of structure and content, HTML tables already provide accessible ways to navigate content via cells <td> and headers <th>.

Keyboard navigation

The Tab key should only place the focus on interactive elements like sortable headers, expands and links. If a cell does not contain interactive content, tabbing should skip the cell. Enter, Space and Return activate buttons and other controls after focusing. Arrow keys can be used to scroll table content vertically and horizontally.

Other considerations

Internally, Gestalt Table implements visually-hidden captions through the accessibilityLabel prop. Therefore, if we want to add visual captions (at the top or bottom of the Table), we must prevent redundancy. Any top or bottom text that describes the Table should be removed from navigation using aria-hidden.

See the examples below for more details.

Top captions
Bottom captions

Subcomponents

Table.Body Props

Table.Body subcomponent props
Name
Type
Default
children
React.Node
-

Table.Cell Props

Table.Cell subcomponent props
Name
Type
Default
children
React.Node
-
colSpan
number
1
rowSpan
number
1

Table.Footer Props

Table.Footer subcomponent props
Name
Type
Default
children
React.Node
-

Table.Header Props

Table.Header subcomponent props
Name
Type
Default
children
React.Node
-
boolean
false

If true, the table header will be sticky and the table body will be scrollable

Table.HeaderCell Props

Table.HeaderCell subcomponent props
Name
Type
Default
children
React.Node
-
colSpan
number
1
rowSpan
number
1
scope
"col" | "row" | "colgroup" | "rowgroup"
"col"

Table.Row Props

Table.Row subcomponent props
Name
Type
Default
children
React.Node
-

Table.RowExpandable Props

Table.RowExpandable subcomponent props
Name
Type
Default
accessibilityCollapseLabel
Required
string
-

Supply a short, descriptive label for screen-readers as a text alternative to the Collapse button.

Accessibility: It populates aria-label on the <button> element for the Collapse button.

accessibilityExpandLabel
Required
string
-

Supply a short, descriptive label for screen-readers as a text alternative to the Expand button.

Accessibility: It populates aria-label on the <button> element for the Expand button.

expandedContents
Required
React.Node
-
id
Required
string
-
children
React.Node
-
hoverStyle
"none" | "gray"
"gray"
onExpand
({ event: SyntheticMouseEvent<HTMLButtonElement> | SyntheticKeyboardEvent<HTMLButtonElement> | SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement> expanded: boolean }) => void
-

Callback fired when the expand button component is clicked

Table.SortableHeaderCell Props

Table.SortableHeaderCell subcomponent props
Name
Type
Default
onSortChange
Required
({ event: SyntheticMouseEvent<HTMLTableCellElement> | SyntheticKeyboardEvent<HTMLTableCellElement> }) => void
-
sortOrder
Required
"asc" | "desc"
-
status
Required
"active" | "inactive"
-
children
React.Node
-
colSpan
number
1
rowSpan
number
1
scope
"col" | "row" | "colgroup" | "rowgroup"
"col"

Variants

Sticky Column

Try scrolling horizontally to see the first column remain in place.

Multiple sticky columns

Try scrolling horizontally to see the first 3 columns remain in place.

Sticky header and sticky columns

Try scrolling horizontally and vertically to see the columns and header remain in place.

Table Row Expandable

Expandable row that is able to hold content that will displayed depending on the clickable expand/collapse button icon.

Table Row Expandable with Sticky Columns

When specifying stickyColumns with expandable rows, include the column of arrows in your count. This example sets stickyColumns to 3.

Sortable header cells

Sortable header cells are clickable in an accessible way and have an icon to display whether the table is currently being sorted by that column.

Sortable header cells with sticky columns

Module
Modules are another way to stack multiple rows of content. However, they are used to show 2 to 3 blocks of related content, whereas Tables are used for large data sets that can be easily scanned and compared across multiple rows and columns.

Checkbox
Checkboxes are often used in tables to allow for selecting and editing of multiple rows at once.

Edit page on GitHub