​​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.

Basic Table
Name
House
Birthday
Luna Lovegood
Ravenclaw
June 25, 1993
Draco Malfoy
Slytherin
December 3, 1992
Hermione Granger
Gryffindor
September 19, 1979
Neville Longbottom
Gryffindor
July 30, 1980

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

Example of a 'do' for table style
Status
Campaign
Engagement
Awareness
Catalogs
Awareness
Conversions
Do

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

Example of a Dont do for table style
Status
Campaign
Engagement
Awareness
Catalogs
Awareness
CONVERSIONS
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

Example of a 'do' for table alignment
Campaign
Spend
$5.50
$3,000.00
$1.75
$51,650,500.54
$67.60
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
Example of a 'Dont' do for table alignment
Campaign
Spend
$5
$3,000.00
$1.750
$51,650,500.54
$67.60
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
Another example of a 'do' for table alignment
Status
Rate
Type
Active
Ends 11/20/2021
100
CTR
Paused
Ends 11/20/2021
5,000
Engagement
Warning
Ends 11/20/2021
2
Conversions
Complete
Ends 11/20/2021
50
CTR
Do

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

Another Example of a 'Dont' do for table alignment
Status
Rate
Active
Ends 11/20/2021
100 CTR
Paused
Ends 11/20/2021
5,000 Engagement
Warning
Ends 11/20/2021
2 Conversions
Complete
Ends 11/20/2021
50 CTR
Don't

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

Content

Example of a 'do' for table content
Name
Total
Video views for all Q3 campaigns and ad groups
David Brown, Carlota Ojeda, Olamide Olufemi, Rajesh Uttambai
--
Video views for all Q2 campaigns and ad groups
David Brown, Carlota Ojeda
5,000
Video views for all Q2 ad groups
David Brown, Carlota Ojeda, Olamide Olufemi, Rajesh Uttambai
6,455,434
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.
Example of a 'don't' do for table content
Name
Total amounts for 2021 through 2022
Video views for all Q3 campaigns and ad groups
David Brown, Carlota Ojeda, Olamide Olufemi, Rajesh Uttambai
Video views for all Q2 campaigns and ad groups
David Brown, Carlota Ojeda
5,000
Video views for all Q2 ad groups
David Brown, Carlota Ojeda, Olamide Olufemi, Rajesh Uttambai
6,455,434
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.
Another Example of a 'do' for table content
Open/Close row
Name
Team
Role
Office Hours
Ayesha Teng
Gestalt
Engineer
Monday, Friday
Ryan Costa
Analytics
Designer
Wednesdays
Kate Steele
Monetization
Design Technologist
Tuesdays, Thursdays
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.

Another example of a 'don't' do for table content
Open/Close row
Campaing
Status
Budget
Scope
December '21
Active
$100,000
Global
January '22
Draft
$50,000
Japan, Germany, Canada, Spain, Mexico, Thailand, Italy
February '22
Draft
$50,000
Japan, Germany, Canada
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.

Your campaigns summary
Status
Campaign
In progress
Ends 11/20/2021
Paused
Ends 11/20/2021
Warning
Ends 11/20/2021
Complete
Ends 11/20/2021
Top captions
Your campaigns summary
Status
Campaign
In progress
Ends 11/20/2021
Paused
Ends 11/20/2021
Warning
Ends 11/20/2021
Complete
Ends 11/20/2021
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 header
Image
Name
House
Luna
Luna Lovegood
Ravenclaw
Draco
Draco Malfoy
Slytherin
Neville
Neville Longbottom
Gryffindor

Sticky Column

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

Sticky Column
Image
Name
Super Name
Favorite Food
Best Friend
Birthday
Tony
Tony Stark
Iron Man
Shawarma
Spiderman
May 29, 1970
Peter
Peter Parker
Spiderman
Sandwiches
Iron Man
December 28, 1995
T'Challa
T'Challa
Black Panther
Beef suya
Shuri
November 28, 1977

Multiple sticky columns

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

Multiple sticky columns
Image
Name
Super Name
Best Friend
Favorite Food
Super Powers
Home
Aliases
Tony
Tony Stark
Iron Man
Spiderman
Shawarma
Flight, Super strength
New York
N/A
Peter
Peter Parker
Spiderman
Iron Man
Sandwiches
Spidey senses, super strength, web shooters
Brooklyn
Friendly Neighborhood Spiderman
Wanda
Wanda Maximoff
Scarlet Witch
Vision
Chicken paprikash
Chaos magic, spells, reality warping
Sokovia
N/A
Black Panther
T'Challa
Black Panther
Shuri
Beef suya
Enhanced strength, speed, reflexes + Vibranium suit
Wakanda
King of the Dead

Sticky header and sticky columns

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

Sticky header and sticky columns
Image
Name
Super Name
Best Friend
Favorite Food
Super Powers
Home
Aliases
Tony
Tony Stark
Iron Man
Spiderman
Shawarma
Flight, Super strength
New York
N/A
Peter
Peter Parker
Spiderman
Iron Man
Sandwiches
Spidey senses, super strength, web shooters
Brooklyn
Friendly Neighborhood Spiderman
Wanda
Wanda Maximoff
Scarlet Witch
Vision
Chicken paprikash
Chaos magic, spells, reality warping
Sokovia
N/A
Black Panther
T'Challa
Black Panther
Shuri
Beef suya
Enhanced strength, speed, reflexes + Vibranium suit
Wakanda
King of the Dead

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
Open/Close row
Name
House
Birthday
Luna Lovegood
Ravenclaw
June 25, 1993
Draco Malfoy
Slytherin
December 3, 1992
Neville Longbottom
Gryffindor
July 30, 1980

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.

Table Row Expandable with Sticky Columns
Open/Close row
Name
Super Name
Best Friend
Favorite Food
Home
Alias
Super Powers
Tony Stark
Iron Man
Spiderman
Shawarma
New York City
N/A
Flight, Super strength
Wanda Maximoff
Scarlet Witch
Vision
Chicken paprikash
Sokovia
Wanda Frank
Chaos magic, spells, reality warping
T'Challa
Black Panther
Shuri
Beef suya
Wakana
King of the Dead
Enhanced strength, speed, reflexes + Vibranium suit

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
Name
Id

Sortable header cells with sticky columns

Sortable header cells with sticky columns
Name
Nickname
Favorite Food
Best Friend
Birthdate
Description
Favorite Color