Table

View source on GitHub

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.

children
Required
React.ChildrenArray<React.Element<typeof Table.Body | typeof Table.Footer | typeof Table.Header>>
-

Must be instances of Table.Header, Table.Body, and/or Table.Footer components. See the Subcomponent section to learn more.

borderStyle
"sm" | "none"
-

Specify a border width for Table: "sm" is 1px.

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, multiple sticky columns, sticky header and columns, expandable row with sticky columns, and sortable header cells with sticky columns variants 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.Header

Use Table.Header to group the header content in Table.

Table.Header Props

Table.Header subcomponent props
Name
Type
Default
children
Required
React.Element<typeof Table.Row>
-

Must be an instance of Table.Row. See the Subcomponent section to learn more.

sticky
boolean
false

If true, the table header will be sticky and the table body will be scrollable. See the sticky Header and the sticky header and columns variants for details.

Table.Body

Use Table.Body to group the body content in Table.

Table.Body Props

Table.Body subcomponent props
Name
Type
Default
children
Required
React.ChildrenArray<React.Element<typeof Table.Row | typeof Table.RowExpandable>>
-

Must be instances of Table.Row and/or Table.RowExpandable components. See the Subcomponent section to learn more.

Table.Footer

Use Table.Footer to group the footer content in Table.

Table.Footer Props

Table.Footer subcomponent props
Name
Type
Default
children
Required
React.ChildrenArray<React.Element<typeof Table.Row | typeof Table.RowExpandable>>
-

Must be instances of Table.Row and/or Table.RowExpandable components. See the Subcomponent section to learn more.

Table.Cell

Use Table.Cell for individual table values.

Table.Cell Props

Table.Cell subcomponent props
Name
Type
Default
children
Required
React.Node
-

The content of the table cell.

colSpan
number
-

colSpan defines the number of columns a cell should span.

rowSpan
number
-

rowSpan defines the number of rows a cell should span.

Table.HeaderCell

Use Table.HeaderCell to define a header cell in Table.

Table.HeaderCell Props

Table.HeaderCell subcomponent props
Name
Type
Default
children
Required
React.Node
-

The content of the table cell.

colSpan
number
-

colSpan defines the number of columns a cell should span.

rowSpan
number
-

rowSpan defines the number of rows a cell should span.

scope
"col" | "colgroup" | "row" | "rowgroup"
-

The scope attribute specifies whether a header cell is a header for a column, row, or group of columns or rows. The scope attribute has no visual effect, but is used by screen readers and other assistive technologies.

Table.SortableHeaderCell

Use Table.SortableHeaderCell to define a header cell with sorting functionality in Table.

Table.SortableHeaderCell Props

Table.SortableHeaderCell subcomponent props
Name
Type
Default
children
Required
React.Node
-

The content of the table cell.

onSortChange
Required
({| event: | SyntheticMouseEvent<HTMLDivElement> | SyntheticKeyboardEvent<HTMLDivElement> | SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>, dangerouslyDisableOnNavigation: () => void, |}) => void
-

Callback fired when the sort button component is clicked.

sortOrder
Required
"asc" | "desc"
-

Sets the sorting direction: sortOrder="asc" is ascending (A to Z) and sortOrder="desc" is descending (Z to A):

status
Required
"active" | "inactive"
-

Disables the sorting functionality for a column.

colSpan
number
-

colSpan defines the number of columns a cell should span.

rowSpan
number
-

rowSpan defines the number of rows a cell should span.

scope
"col" | "colgroup" | "row" | "rowgroup"
-

The scope attribute specifies whether a header cell is a header for a column, row, or group of columns or rows. The scope attribute has no visual effect in ordinary web browsers, but can be used by screen readers.

Table.Row

Use Table.Row to define a row in Table.

Table.Row Props

Table.Row subcomponent props
Name
Type
Default
children
Required
React.ChildrenArray<React.Element<typeof Table.Cell | typeof Table.HeaderCell | typeof Table.SortableHeaderCell>>
-

Must be instances of Table.Cell, Table.HeaderCell, or Table.SortableHeaderCell components. See the Subcomponent section to learn more.

Table.RowExpandable

Use Table.RowExpandable to define a row that expands and collapses additional content.

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.

children
Required
React.ChildrenArray<React.Element<typeof Table.Cell>>
-

Must be instances of Table.Cell. See the Subcomponent section to learn more.

expandedContents
Required
React.Node
-

The contents to show and/or hide on an expandable row.

id
Required
string
-

Unique id for Table.RowExpandable.

hoverStyle
"gray" | "none"
"gray"

Sets the background color on hover over the row.

onExpand
({| event: | SyntheticMouseEvent<HTMLButtonElement> | SyntheticKeyboardEvent<HTMLButtonElement> | SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>, expanded: boolean, |}) => void
-

Callback fired when the expand button component is clicked.

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