Skip to contentSkip to navigationSkip to topbar
Paste
Paste assistant Assistant
FigmaStar

Table

Version 8.2.1GithubStorybook

A Table is a collection of information displayed across columns and rows.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th>Date</Th>

      <Th>SID</Th>

      <Th>From</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SM0yc4mxi6cn4z13bte7qmflc2drc85mlp

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMl29llgoihx286uhxfb0yc5n0sg391x5n

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMxarke3v30fv17hauqn86a7nhgm3b5d87

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

  </TBody>

</Table>

Guidelines

Guidelines page anchor

About Table

About Table page anchor

A Table is a grid of static textual and numeric data of the same content structure presented in rows and columns of cells. For example, a Table would be a good way to represent a list of multiple support agents and their respective skills and online/offline status.

Accessibility

Accessibility page anchor

Tables are used to organize data with a logical relationship in grids. Accessible tables need HTML markup that indicates header cells and data cells and defines their relationship. Assistive technologies use this information to provide context to users.

Accessibility requirements:

  • Tables must have a THead, containing a Th for each column.
  • Tables must have a TBody wrapping the table body of rows.

Accessibility recommendations:

  • It is a best practice to include row headers, which can be added by including a header (Th) as the first cell in each row (Tr), with scope="row". This is not relevant for all tables, but you should follow this practice when the first cell in a row is the key value for that row, such as a username. You can find an example of this in the section on row headers.
  • Any component can be placed in a Table, but tables should only contain static textual and numeric data, rather than actionable components like buttons, whenever possible. This is because, if the table is reasonably long—say 50 rows—with multiple actions per row—say 4 actions—a keyboard-only user would have to press the tab key 200 times to get past that table. If you do need to include interactive elements (such as linking to object details, selecting rows, or deleting rows), use Data Grid instead.
(information)

Accessibility insight: navigating tables with a screen reader

Learn more about why semantic table markup is important in this demo video by Inclusive Components(link takes you to an external page)that shows what it's like to explore a data table with a screen reader.

Examples

Examples page anchor

Layouts

Layouts page anchor

Default

Default page anchor

The Default Table uses an automatic table layout algorithm dictated by the browser. The width of the table cells are adjusted to fit the content.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th>Date</Th>

      <Th>SID</Th>

      <Th>From</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SM0yc4mxi6cn4z13bte7qmflc2drc85mlp

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMl29llgoihx286uhxfb0yc5n0sg391x5n

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMxarke3v30fv17hauqn86a7nhgm3b5d87

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

  </TBody>

</Table>

Fixed column width

Fixed column width page anchor

The Fixed Table variant sets equal column widths for the table.

Component preview theme
<Table tableLayout="fixed">

  <THead>

    <Tr>

      <Th>Agents</Th>

      <Th>Skills</Th>

      <Th textAlign="right">Tasks</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Th scope="row">Adam Brown</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">35</Td>

    </Tr>

    <Tr>

      <Th scope="row">Adriana Lovelock</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">28</Td>

    </Tr>

    <Tr>

      <Th scope="row">Amanda Cutlack</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">7</Td>

    </Tr>

  </TBody>

  <TFoot>

    <Tr>

      <Td/>

      <Td/>

      <Td textAlign="right">70</Td>

    </Tr>

  </TFoot>

</Table>

Specified column widths

Specified column widths page anchor

THead cells (Th) can be given a width in order to fill a section of the Table row (Tr). Widths can be set with Paste Size Tokens or a number value, e.g. 120px.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th width="size20">First name</Th>

      <Th>Last name</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Td>Tamir</Td>

      <Td>Rice</Td>

    </Tr>

    <Tr>

      <Td>Philando</Td>

      <Td>Castile</Td>

    </Tr>

    <Tr>

      <Td>Trayvon</Td>

      <Td>Martin</Td>

    </Tr>

    <Tr>

      <Td>Breonna</Td>

      <Td>Taylor</Td>

    </Tr>

    <Tr>

      <Td>Shantel</Td>

      <Td>Davis</Td>

    </Tr>

    <Tr>

      <Td>Walter</Td>

      <Td>Scott</Td>

    </Tr>

  </TBody>

</Table>

Responsive Layouts

Responsive Layouts page anchor

Tabular data on small screens can be problematic. The data can often cause tables to overflow the browser window. If you need to support small screens, you can set scrollHorizontally and the table will scroll horizontally when the data can no longer fit on the screen.

Component preview theme
<Table scrollHorizontally>

  <THead>

    <Tr>

      <Th>Date</Th>

      <Th>SID</Th>

      <Th>From</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Td>

        16:24:28 PDT 2020-09-17

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SM0yc4mxi6cn4z13bte7qmflc2drc85mlp

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        16:24:28 PDT 2020-09-17

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMl29llgoihx286uhxfb0yc5n0sg391x5n

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        16:24:28 PDT 2020-09-17

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMxarke3v30fv17hauqn86a7nhgm3b5d87

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

  </TBody>

</Table>

Density

Density page anchor

You can control a tables vertical density by either setting noWrap on the table. This will ensure table cell content stays on a single line.

You can also optionally set the whiteSpace prop on individual table cells, for more granular control.

Coupled with a fixed table layout and truncation you can increase the data density of a table dramatically. You should be extremely mindful of readability trade-offs when doing so.

Component preview theme
<Table scrollHorizontally noWrap>

  <THead>

    <Tr>

      <Th>Date</Th>

      <Th>SID</Th>

      <Th>From</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Td>

        16:24:28 PDT 2020-09-17

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SM0yc4mxi6cn4z13bte7qmflc2drc85mlp

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td whitespace="wrap">

        16:24:28 PDT 2020-09-17

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMl29llgoihx286uhxfb0yc5n0sg391x5n

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        16:24:28 PDT 2020-09-17

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMxarke3v30fv17hauqn86a7nhgm3b5d87

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

  </TBody>

</Table>

Alignment

Alignment page anchor

Column alignment

Column alignment page anchor

You can adjust the text alignment within Table cells (Td or Th). By default they are left-aligned.

In general, text should be left-aligned, numbers should be right-aligned, and the header should be aligned with the data. Data should rarely ever be centered. Numbers only need to be right-aligned when they indicate size or are meant to be compared to each other. Numbers like ID numbers, phone numbers, etc. should stay left-aligned.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th>First name</Th>

      <Th textAlign="right">Last name</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Td>Tamir</Td>

      <Td textAlign="right">Rice</Td>

    </Tr>

    <Tr>

      <Td>Philando</Td>

      <Td textAlign="right">Castile</Td>

    </Tr>

    <Tr>

      <Td>Trayvon</Td>

      <Td textAlign="right">Martin</Td>

    </Tr>

    <Tr>

      <Td>Breonna</Td>

      <Td textAlign="right">Taylor</Td>

    </Tr>

    <Tr>

      <Td>Shantel</Td>

      <Td textAlign="right">Davis</Td>

    </Tr>

    <Tr>

      <Td>Walter</Td>

      <Td textAlign="right">Scott</Td>

    </Tr>

  </TBody>

</Table>

Row alignment

Row alignment page anchor

Table rows (Tr) can be set with either top, middle, or bottom vertical alignment. By default they are middle-aligned.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th width="size20">Author</Th>

      <Th>Quote</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr verticalAlign="top">

      <Th scope="row">Chinua Achebe</Th>

      <Td>The impatient idealist says: ‘Give me a place to stand and I shall move the earth.' But such a place does not exist. We all have to stand on the earth itself and go with her at her pace.</Td>

    </Tr>

    <Tr verticalAlign="middle">

      <Th scope="row">James Baldwin</Th>

      <Td>Anyone who has ever struggled with poverty knows how extremely expensive it is to be poor.</Td>

    </Tr>

    <Tr verticalAlign="middle">

      <Th scope="row">Dorothy West</Th>

      <Td>To know how much there is to know is the beginning of learning to live.</Td>

    </Tr>

    <Tr verticalAlign="bottom">

      <Th scope="row">W.E.B. Du Bois</Th>

      <Td>Herein lies the tragedy of the age: not that men are poor—all men know something of poverty; not that men are wicked—who is good? Not that men are ignorant—what is truth? Nay, but that men know so little of men.</Td>

    </Tr>

  </TBody>

</Table>

Borderless

Borderless page anchor

Tables can support a borderless variant, which can be useful in cases where the Table is placed inside of another containing element, such as a modal or a card. Tables have borders by default, but these can optionally be turned off by setting variant="borderless" on Table.

Component preview theme
<Card>

  <Table variant="borderless">

    <THead>

      <Tr>

        <Th>Agents</Th>

        <Th>Skills</Th>

        <Th textAlign="right">Tasks</Th>

      </Tr>

    </THead>

    <TBody>

      <Tr>

        <Th scope="row">Adam Brown</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">35</Td>

      </Tr>

      <Tr>

        <Th scope="row">Adriana Lovelock</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">28</Td>

      </Tr>

      <Tr>

        <Th scope="row">Amanda Cutlack</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">7</Td>

      </Tr>

    </TBody>

    <TFoot>

      <Tr>

        <Td/>

        <Td/>

        <Td textAlign="right">70</Td>

      </Tr>

    </TFoot>

  </Table>

</Card>

Row headers

Row headers page anchor

Tables support row headers in addition to the more commonly seen column headers. It is a best practice to provide row headers in cases where the first cell in a row is the key value for that row, such as a username or the name of an email campaign.

Row headers can be added by including a Th as the first cell in each Tr, with scope="row".

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th>User</Th>

      <Th>Email address</Th>

      <Th>Last log-in time</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Th scope="row">tamir.rice</Th>

      <Td>tamir@rice.com</Td>

      <Td>12:24:00 PDT</Td>

    </Tr>

    <Tr>

      <Th scope="row">philando.castile</Th>

      <Td>philando@castile.com</Td>

      <Td>08:24:20 PDT</Td>

    </Tr>

    <Tr>

      <Th scope="row">trayvon.martin</Th>

      <Td>trayvon@martin.com</Td>

      <Td>16:05:10 PDT</Td>

    </Tr>

    <Tr>

      <Th scope="row">breonna.taylor</Th>

      <Td>breonna@taylor.com</Td>

      <Td>13:10:28 PDT</Td>

    </Tr>

    <Tr>

      <Th scope="row">shantel.davis</Th>

      <Td>shantel@davis.com</Td>

      <Td>01:04:54 PDT</Td>

    </Tr>

    <Tr>

      <Th scope="row">walter.scott</Th>

      <Td>walter@scott.com</Td>

      <Td>08:19:10 PDT</Td>

    </Tr>

  </TBody>

</Table>
Table with footer page anchor

Tables support an optional TFoot, which comes after the TBody. The TFoot must contain at least one Tr. A good use case for a TFoot is when you want to provide a summary or total for the rows of data in your table.

The placement of the TFoot is based on classic HTML table design, so it can not be placed anywhere except at the bottom of a table. In cases where you do want to show a summary or total, and that information is of high importance to the user, you can place it above the table or at the top of the table in a regular table row, rather than using the TFoot.

Component preview theme
<Table tableLayout="fixed">

  <THead>

    <Tr>

      <Th>Agents</Th>

      <Th>Skills</Th>

      <Th textAlign="right">Tasks</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Th scope="row">Adam Brown</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">35</Td>

    </Tr>

    <Tr>

      <Th scope="row">Adriana Lovelock</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">28</Td>

    </Tr>

    <Tr>

      <Th scope="row">Amanda Cutlack</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">7</Td>

    </Tr>

  </TBody>

  <TFoot>

    <Tr>

      <Th scope="row">Total tasks</Th>

      <Td/>

      <Td textAlign="right">70</Td>

    </Tr>

  </TFoot>

</Table>

Table with sticky header

Table with sticky header page anchor

Tables support a "sticky header", which can be useful in tables with a large amount of data. A sticky header will allow a user to keep the context of what each column contains as they scroll through the data contained in the table.

Set the boolean property stickyHeader on the THead component, to enable the sticky header.

Component preview theme
<Box overflowY="auto" maxHeight="500px">

  <Table tableLayout="fixed">

    <THead stickyHeader top={0}>

      <Tr>

        <Th>Agents</Th>

        <Th>Skills</Th>

        <Th textAlign="right">Tasks</Th>

      </Tr>

    </THead>

    <TBody>

      <Tr>

        <Th scope="row">Adam Brown</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">35</Td>

      </Tr>

      <Tr>

        <Th scope="row">Adriana Lovelock</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">28</Td>

      </Tr>

      <Tr>

        <Th scope="row">Amanda Cutlack</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">7</Td>

      </Tr>

      <Tr>

        <Th scope="row">Sofie Korneliya</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">47</Td>

      </Tr>

      <Tr>

        <Th scope="row">Gerarda Che</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">2</Td>

      </Tr>

      <Tr>

        <Th scope="row">Natalia Hiroshi</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">9</Td>

      </Tr>

      <Tr>

        <Th scope="row">Gaël Kambiz</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">18</Td>

      </Tr>

      <Tr>

        <Th scope="row">Amelina Muriel</Th>

        <Td>English, French, Sales, Spanish</Td>

        <Td textAlign="right">29</Td>

      </Tr>

      <Tr>

        <Th scope="row">Luisa Hipólito</Th>

        <Td>English, French</Td>

        <Td textAlign="right">9</Td>

      </Tr>

      <Tr>

        <Th scope="row">Machteld Vašek</Th>

        <Td>English, Spanish</Td>

        <Td textAlign="right">18</Td>

      </Tr>

      <Tr>

        <Th scope="row">Cayetano Helmuth</Th>

        <Td>French</Td>

        <Td textAlign="right">29</Td>

      </Tr>

    </TBody>

    <TFoot>

      <Tr>

        <Th scope="row">Total tasks</Th>

        <Td/>

        <Td textAlign="right">70</Td>

      </Tr>

    </TFoot>

  </Table>

</Box>

Composition Notes

Composition Notes page anchor

Tables must be created using a combination of:

  • Table: The table wrapper
  • THead: The header of your table
  • TBody: The main body of your table
  • TFoot: The footer of your table (optional)
  • Tr: A row of cells in your table
  • Th: A header cell which can be used as a column title and row title
  • Td: A cell of table content

Tables fill 100% width of the space of their containing element. Use Layout components, like Grid, to control the size and placement of Tables within a page.

Formatting

Formatting page anchor

Columns

Columns page anchor

In many cases, each table row has some kind of identifier, such as a username, SID, or friendly name. In cases where the data in each row is associated with an overarching, named object, the name of that object should generally be the first column in the table. In these cases, the cells in that first column should be Row Headers.

To determine the order of the remaining columns, conduct usability testing to find out what column ordering works best for your users and their particular needs. Generally, it is a good practice to put columns that are closely related to one another (such as a unit price, quantity purchased, and total price) near each other in a table.

If the data contained in a particular column has a measurement symbol, like a percentage, include the symbol in the column header rather than including it in each cell.

When data is represented using decimals, keep the number of decimal places consistent.

Text alignment in cells

Text alignment in cells page anchor

In general, text should be left-aligned, numbers should be right-aligned, and the header should be aligned with the data. Data should rarely ever be centered. Numbers only need to be right-aligned when they indicate size and/or are meant to be compared to each other. Numbers like ID numbers, phone numbers, etc. should stay left-aligned.

Zebra striping

Zebra striping page anchor

Tables can have zebra stripes (i.e. alternating row highlighting), which can improve readability of particularly large data sets. Tables have zebra stripes turned off by default, but these can optionally be turned on by setting striped on Table.

Component preview theme
<Table striped>

  <THead>

    <Tr>

      <Th>Agents</Th>

      <Th>Skills</Th>

      <Th textAlign="right">Tasks</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Th scope="row">Adam Brown</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">35</Td>

    </Tr>

    <Tr>

      <Th scope="row">Adriana Lovelock</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">28</Td>

    </Tr>

    <Tr>

      <Th scope="row">Amanda Cutlack</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">7</Td>

    </Tr>

  </TBody>

  <TFoot>

    <Tr>

      <Th scope="row">Total tasks</Th>

      <Td/>

      <Td textAlign="right">70</Td>

    </Tr>

  </TFoot>

</Table>

Table with description text

Table with description text page anchor

Each individual table cell can support multiple rows of text, which we'll refer to as "description text". This is useful when you want to provide related details in a table without adding additional columns, such as placing a user's email address beneath their username in a single cell under a column header titled "user".

Description text is recommended in cases where the user would benefit from having additional context about a particular cell, but that additional context is not the primary data that is being presented in the table. For example, in a table that lists a user's email campaigns with open rates, click rates, etc. for each, it may help the user identify a particular campaign by knowing both the campaign name and what time it was sent, so the first column of this table may include the campaign name with the send time included as description text. In this example, the send time is not being compared across rows like the open rates and click rates are; instead, the send time is used to add additional detail that helps the user identify and understand data in an individual row.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th>User</Th>

      <Th>Skills</Th>

      <Th textAlign="right">Tasks</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Th scope="row">

        <Text as="span">

          Adam Brown

        </Text>

        <DetailText marginTop='space0'>adam@brown.com</DetailText>

      </Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">35</Td>

    </Tr>

    <Tr>

      <Th scope="row">

        <Text as="span">

          Adriana Lovelock

        </Text>

        <DetailText marginTop='space0'>adriana@lovelock.com</DetailText>

      </Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">28</Td>

    </Tr>

    <Tr>

      <Th scope="row">

        <Text as="span">

          Amanda Cutlack

        </Text>

        <DetailText marginTop='space0'>amanda@cutlack.com</DetailText>

      </Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">7</Td>

    </Tr>

  </TBody>

</Table>

Table with avatars

Table with avatars page anchor

Tables can be composed using Avatar, which can be used to make a table of user data more scannable. You can put an avatar next to a user's first and last name using Stack inside a single Td.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th>User</Th>

      <Th>Skills</Th>

      <Th textAlign="right">Tasks</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Th scope="row">

        <Stack orientation="horizontal" spacing="space40">

          <Avatar size="sizeIcon60" name="Adam Brown" src="/images/avatars/avatar1.png" />

          <Box>

            <Text as="p">

              Adam Brown

            </Text>

            <Text as="p" color="colorTextWeak" fontWeight="fontWeightNormal">adam@brown.com</Text>

          </Box>

        </Stack>

      </Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">35</Td>

    </Tr>

    <Tr>

      <Th scope="row">

        <Stack orientation="horizontal" spacing="space40">

          <Avatar size="sizeIcon60" name="Adriana Lovelock" src="/images/avatars/avatar4.png" />

          <Box>

            <Text as="p">

              Adriana Lovelock

            </Text>

            <Text as="p" color="colorTextWeak" fontWeight="fontWeightNormal">adriana@lovelock.com</Text>

          </Box>

        </Stack>

      </Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">28</Td>

    </Tr>

    <Tr>

      <Th scope="row">

        <Stack orientation="horizontal" spacing="space40">

          <Avatar size="sizeIcon60" name="Amanda Cutlack" src="/images/avatars/avatar3.png" />

          <Box>

            <Text as="p">

              Amanda Cutlack

            </Text>

            <Text as="p" color="colorTextWeak" fontWeight="fontWeightNormal">amanda@cutlack.com</Text>

          </Box>

        </Stack>

      </Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td textAlign="right">7</Td>

    </Tr>

  </TBody>

</Table>

Table with status indicators

Table with status indicators page anchor

Tables can support custom compositions using Box and Text, such as custom status indicators. When including statuses in a table, be sure to include supporting text so color isn't the only indicator of status.

Refer to our Status Indicator pattern (coming soon!) for guidance on displaying statuses in your tables.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th>Result</Th>

      <Th>SID</Th>

      <Th>Email address</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Td>

        <Box display="flex" alignItems="center">

          <ProcessSuccessIcon

            color="colorTextIconSuccess"

            decorative={false}

            title="valid" />

          <Text as="p" marginLeft="space20">Valid</Text>

        </Box>

        <Text as="p" color="colorTextWeak" marginLeft="space70">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SM0yc4mxi6cn4z13bte7qmflc2drc85mlp

        </Text>

      </Td>

      <Td>hayden74@hotmail.com</Td>

    </Tr>

    <Tr>

      <Td>

        <Box display="flex" alignItems="center">

          <ProcessWarningIcon

            color="colorTextIconWarning"

            decorative={false}

            title="risky" />

          <Text as="p" marginLeft="space20">Risky</Text>

        </Box>

        <Text as="p" color="colorTextWeak" marginLeft="space70">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMl29llgoihx286uhxfb0yc5n0sg391x5n

        </Text>

      </Td>

      <Td>beyrek70@hotmail.com</Td>

    </Tr>

    <Tr>

      <Td>

        <Box display="flex" alignItems="center">

          <ProcessErrorIcon

            color="colorTextIconError"

            decorative={false}

            title="invalid" />

          <Text as="p" marginLeft="space20">Invalid</Text>

        </Box>

        <Text as="p" color="colorTextWeak" marginLeft="space70">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMxarke3v30fv17hauqn86a7nhgm3b5d87

        </Text>

      </Td>

      <Td>kevin@hotmail.com</Td>

    </Tr>

  </TBody>

</Table>

Table with tooltips on headers

Table with tooltips on headers page anchor

A Th can be composed to include icon buttons, such as an information icon button with additional details placed in a Tooltip or Popover.

Component preview theme
<Table>

  <THead>

    <Tr>

      <Th>Date</Th>

      <Th>

        <Box display="flex" alignItems="center">

          <Text as="span" marginRight="space10">SID</Text>

          <Tooltip text="SID Number">

            <Button variant="reset" size="reset">

              <InformationIcon decorative={false} title="Open Tooltip" display="block" />

            </Button>

          </Tooltip>

        </Box>

      </Th>

      <Th>From</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SM0yc4mxi6cn4z13bte7qmflc2drc85mlp

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMl29llgoihx286uhxfb0yc5n0sg391x5n

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

    <Tr>

      <Td>

        <Text as="p">16:24:28 PDT</Text>

        <Text as="p">2020-09-17</Text>

      </Td>

      <Td>

        <Text as="span" fontFamily="fontFamilyCode">

          SMxarke3v30fv17hauqn86a7nhgm3b5d87

        </Text>

      </Td>

      <Td>(602) 609-6747</Td>

    </Tr>

  </TBody>

</Table>

Table with truncated cells

Table with truncated cells page anchor

In rare cases, you may want to truncate the text in a given cell. For example, when a table contains long URLs, and the user does not need to read the full URL.

Component preview theme
<Table tableLayout="fixed">

  <THead>

    <Tr>

      <Th>Agents</Th>

      <Th>Skills</Th>

      <Th>Profile URL</Th>

    </Tr>

  </THead>

  <TBody>

    <Tr>

      <Th scope="row">Adam Brown</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td>

        <Truncate title="Learn more about Paste">

          <Anchor href="/introduction/about-paste">

            https://paste.twilio.design/introduction/about-paste

          </Anchor>

        </Truncate>

      </Td>

    </Tr>

    <Tr>

      <Th scope="row">Adriana Lovelock</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td>

        <Truncate title="Learn more about Paste">

          <Anchor href="/introduction/about-paste">

            https://paste.twilio.design/introduction/about-paste

          </Anchor>

        </Truncate>

      </Td>

    </Tr>

    <Tr>

      <Th scope="row">Amanda Cutlack</Th>

      <Td>English, French, Sales, Spanish</Td>

      <Td>

        <Truncate title="Learn more about Paste">

          <Anchor href="/introduction/about-paste">

            https://paste.twilio.design/introduction/about-paste

          </Anchor>

        </Truncate>

      </Td>

    </Tr>

  </TBody>

</Table>

Displaying missing data

Displaying missing data page anchor

If the data grid is not capable of showing data yet (for example, if it’s in a draft state), leave cells blank.

If a piece of data is missing because the metric in a certain column does not apply to a given row, show “N/A” and use the HTML abbreviation element to communicate the full meaning of the abbreviation (“Not applicable”). This ensures any customers using assistive technologies will understand the cell entry.

Errors

Errors page anchor

Avoid documenting an entire error message within a row. Use an indicator, like an icon or an icon with a short message. The short message can be displayed in a Popover on the icon, or in a cell. Then use other methods, like a Popover, Side Modal, or full page to communicate complete error and resolution information.

When multiple errors affect a single row, indicate the number of errors and provide specific error and resolution information within a Popover, Side Modal, or full page.

When an error affects an entire column, consider an indicator near the column header with additional information available in a popover or other component.

When all data in a Data Grid does not load, show an error empty state.

When to use Table

When to use Table page anchor

Tables are used to represent static, tabular data. For example, a list of users' first names, last names, and email addresses.

Do

Left-align textual table data, such as an email address.

Don't

Don't right- or center-align textual table data.

Do

Right-align numeric table data that is meant to be compared along a single column, such as the open rate on an email campaign.

Don't

Don't left- or center-align numeric table data that is meant to be compared along a single column.

Do

Provide numeric data that is meant to be compared along a single column at the same level of precision, so that the decimal point aligns across all rows and the numbers can be easily compared. For example, show all numbers to two decimal places.

Don't

Don't provide numeric data that is meant to be compared along a single column at differing levels of precision. For example, don't show some numbers to one decimal place and others to two.

Do

Include supporting text when providing a status in a table row.

Don't

Don't use color as the only indicator of status in a table row.