Table

Tables are an efficient way of displaying sets of repeating data with the same structure.

Anatomy - Tables

Example of the anatomy of a Table.

  1. Column Header: Includes column labels and extra functionality such as sort and filter.
  2. Cell: Supported Table widgets display here.

Usage Guidance

Data Tables are intended to display data that can be easily scanned and compared.

  • Conceptually, each row in a Table represents an item, and each cell of that row is an attribute of that item.
  • This means that all the cells in a particular column will be the same data type such as dates, numerals, text, etc.
  • Ideally, there should be one value per cell. Field sets are discouraged.
  • Nested Tables are highly discouraged.

When to Use

Use tables to allow users to:

  • Easily scan and compare data
  • View and edit data
  • Manipulate and navigate through a large amount of data
  • Preview data

When to Use Something Else

Consider another component when:

  • You only have a small data set.
  • A more detailed amount of information needs to be displayed by default.
  • There is more than one piece of information within a cell.

Examples

Basic Example

Table includes a container Table component and a TableRow component. Table is a simple wrapper of the <table> element with Canvas styles. TableRow wraps <tr> and supports additional props to customize the style of the row.

Use Table and TableRow in conjunction with the standard <thead> and <tbody> elements to create your Table.

IDNamePositionLocation
1Aidan BrownProduct ManagerSan Francisco, CA
2Betty ChenProduct DesignerSan Francisco, CA
3Helen GonzalezApplication DeveloperPortland, OR
4Timothy MayVP, Product DevelopmentSan Francisco, CA
5John HoursProduct ManagerNew York, New York

Component API

Table

Usage

Table is a simple wrapper of the <table> element with Canvas styles. Use it as you would a standard <table> element.

<Table>
<thead>
<TableRow header={true}>
<th>ID</th>
<th>Name</th>
...
</TableRow>
</thead>
<tbody>
<TableRow>
<td>1</td>
<td>Aidan Brown</td>
...
</TableRow>
...
</tbody>
</Table>

Props

Table does not have any documented props. Undocumented props are spread to its underlying <table> element.

TableRow

Usage

TableRow wraps <tr> and supports additional props to customize the style of the row. Use it as you would a standard <tr> element.

Set the header prop of the TableRow to designate whether or not it contains header elements.

IDNamePositionLocation
1Aidan BrownProduct ManagerSan Francisco, CA

Set the state prop of the TableRow to display it using one of several different visual states. state accepts the following values:

  • TableRow.State.Selected
  • TableRow.State.Alert
  • TableRow.State.InputAlert
  • TableRow.State.Error
  • TableRow.State.InputError
StatePurpose
TableRow.State.AlertWhen there is an issue with the entire row as a whole.
TableRow.State.InputAlertWhen there are issues with one or more (but not all) cells in the row.
TableRow.State.ErrorWhen there is an error with the entire row as a whole.
TableRow.State.InputErrorWhen there are errors with one or more (but not all) cells in the row.
TableRow.State.SelectedIndicates the selected row to the user.

InputAlert and InputError are identical to the Alert and Error states, respectively, except they lack a darkened border around the row.

IDNamePositionLocation
1Aidan BrownProduct ManagerSan Francisco, CA
2Betty ChenProduct DesignerSan Francisco, CA
3Helen GonzalezApplication DeveloperPortland, OR
4Timothy MayVP, Product DevelopmentSan Francisco, CA
5John HoursProduct ManagerNew York, New York
6Leslie LangSoftware ArchitectNew York, New York

Props

Undocumented props are spread to the underlying <tr> element.

NameTypeDefaultDescription
stateTableRowState | undefinedThe state of the TableRow. Accepts `Error`, `Alert`, `InputError`, `InputAlert`, `Hover`, or `Selected`.
headerboolean | undefinedfalseIf true, render the TableRow with header elements.
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef` and spread extra props to a root element.

Accessibility Guidelines

  • No column header cells should be blank.
  • When possible, each cell should only have one piece of data.
  • Avoid placing multiple inactive controls into a single cell.

Content Guidelines

  • When writing titles, column headers, and other text for Tables, refer to the Tables section of the Content Style Guide.

Mobile

PlatformAvailability
iOSYes
AndroidYes

Guidelines

  • Due to screen size limitations, the display of Tables on mobile is different from the desktop display. Rather than displaying inline on the page, there is a tile preview which the user can tap to display a full-page view-only Table. To edit the data in this Table, the user taps the row they wish to edit and an editable form of that row is shown.

    Please note: Tables 2.0 is not currently available for Mobile applications.

Can't Find What You Need?

Check out our FAQ section which may help you find the information you're looking for.

FAQ Section