CMS Design System

Tables show tabular data in columns and rows.

Table with multi headers and a caption

Household members
Name	Street	ZIP code	Employer	Industry
	Address		Employment
John Doe	123 Braavos Ave.	20005	Acme Co.	Healthcare
Jane Doe	456 King's Landing	20005	Acme Co.	Healthcare

Code snippet

<table class="ds-c-table" role="table">
  <caption class="ds-c-table__caption">Household members</caption>
  <col />
  <colgroup span="2"></colgroup>
  <colgroup span="2"></colgroup>
  <thead role="rowgroup">
    <tr role="row">
      <td
        class="ds-c-table__cell--align-left"
        role="columnheader"
        scope="col"
        rowspan="1"
      ></td>
      <th
        class="ds-c-table__cell--align-left ds-u-text-align--center"
        role="columnheader"
        scope="colgroup"
        colspan="2"
      >
        Address
      </th>
      <th
        class="ds-c-table__cell--align-left ds-u-text-align--center"
        role="columnheader"
        scope="colgroup"
        colspan="2"
      >
        Employment
      </th>
    </tr>
    <tr role="row">
      <th class="ds-c-table__cell--align-left" role="columnheader" scope="col">
        Name
      </th>
      <th class="ds-c-table__cell--align-left" role="columnheader" scope="col">
        Street
      </th>
      <th class="ds-c-table__cell--align-left" role="columnheader" scope="col">
        ZIP code
      </th>
      <th class="ds-c-table__cell--align-left" role="columnheader" scope="col">
        Employer
      </th>
      <th class="ds-c-table__cell--align-left" role="columnheader" scope="col">
        Industry
      </th>
    </tr>
  </thead>
  <tbody role="rowgroup">
    <tr role="row">
      <th class="ds-c-table__cell--align-left" role="rowheader" scope="row">
        John Doe
      </th>
      <td class="ds-c-table__cell--align-left" role="cell">123 Braavos Ave.</td>
      <td class="ds-c-table__cell--align-left" role="cell">20005</td>
      <td class="ds-c-table__cell--align-left" role="cell">Acme Co.</td>
      <td class="ds-c-table__cell--align-left" role="cell">Healthcare</td>
    </tr>
    <tr role="row">
      <th class="ds-c-table__cell--align-left" role="rowheader" scope="row">
        Jane Doe
      </th>
      <td class="ds-c-table__cell--align-left" role="cell">
        456 King&#x27;s Landing
      </td>
      <td class="ds-c-table__cell--align-left" role="cell">20005</td>
      <td class="ds-c-table__cell--align-left" role="cell">Acme Co.</td>
      <td class="ds-c-table__cell--align-left" role="cell">Healthcare</td>
    </tr>
  </tbody>
</table>

`<Table>`

Table is a container component that contains TableCaption, TableHead and TableBody as children, as well as TableRow and TableCell for the table content. These components mostly follow ordinary HTML table semantics, but also include some additional responsive features including horizontal scrolling and vertically stacked rows.

View Source File

Scrollable Table

Code snippet

Stackable Table

Code snippet

Table Props

React Properties Documentation
Name	Type	Default	Description
`borderless`	`boolean`		Applies the borderless variation of the table.
`children`required	`React.ReactNode`		The table contents, usually `TableCaption`, `TableHead` and `TableBody`.
`className`	`string`		Additional classes to be added to the root table element.
`compact`	`boolean`		Applies the compact variation of the table.
`scrollable`	`boolean`		Applies a horizontal scrollbar and scrollable notice on `TableCaption` when the `Table`'s contents exceed the container width.
`scrollableNotice`	`React.ReactNode`	`<Alert className="ds-c-table__scroll-alert" role="status"> <p className="ds-c-alert__text">Scroll using arrow keys to see more</p> </Alert>`	Additional text or content to display when the horizontal scrollbar is visible to give the user notice of the scroll behavior. This prop will only be used when the `Table` `scrollable` prop is set and the table width is wider than the viewport.
`stackable`	`boolean`		A stackable variation of the table. When `stackable` is set, `id` or `headers` prop is required in `Table`
`stackableBreakpoint`	`'sm' \| 'md' \| 'lg'`	`'sm'`	Applies responsive styles to vertically stacked rows at different viewport sizes.
`striped`	`boolean`		A striped variation of the table.
`warningDisabled`	`boolean`		Disables the warning message on development console when a responsive stackable table cell does not contain an `id` or `headers`. It's recommended that accessibility with screen readers is tested to ensure the stacked table meets the requirement.

`<TableCaption>`

TableCaption renders the <caption> element.

View Source File

Table Caption Props

React Properties Documentation
Name	Type	Default	Description
`children`	`React.ReactNode`		The table caption contents.
`className`	`string`		Additional classes to be added to the caption element.

`<TableHead>`

TableHead renders the <thead> element and will typically contain TableRow elements to define table columns.

View Source File

Table Head Props

React Properties Documentation
Name	Type	Default	Description
`children`	`React.ReactNode`		The table head contents, usually `TableRow`.

`<TableBody>`

TableBody renders the <tbody> element and will typically contain TableRow elements to define table data.

View Source File

Table Body Props

React Properties Documentation
Name	Type	Default	Description
`children`	`React.ReactNode`		The table body contents, usually `TableRow`.

`<TableRow>`

TableRow renders a <tr> element.

View Source File

Table Row Props

React Properties Documentation
Name	Type	Default	Description
`children`	`React.ReactNode`		The table row contents, usually `TableCell`.

`<TableCell>`

TableCell dynamically renders a <th> or <td> element based on the parent component or user specified component prop. By default TableCell will automatically render a <th> element if the parent component is TableHead, otherwise it will render a <td> element.

View Source File

Table Cell Props

React Properties Documentation
Name	Type	Default	Description
`align`	`'center' \| 'left' \| 'right'`	`'left'`	Set the text-align on the table cell content. Options: left, center, right.
`children`	`React.ReactNode`		The table cell contents.
`component`	`'td' \| 'th'`		When provided, this will render the passed in component as the HTML element. If this prop is undefined, it renders a `<th>` element if the parent component is `TableHead`, otherwise, it renders a `<td>` element.
`className`	`string`		Additional classes to be added to the row element.
`headers`	`string`		`TableCell` must define a `headers` prop for stackable tables with a `<td>` element. The `headers` prop associates header and data cells for screen readers. `headers` consist of a list of space-separated ids that each correspond to a `<td>` element. Read more about the headers attribute.
`id`	`string`		`TableCell` must define an `id` prop for stackable tables with a `<th>` element. The `id` prop associates header and data cells for screen readers.
`scope`	`'row' \| 'col' \| 'rowgroup' \| 'colgroup'`		If this prop is undefined, the component sets a scope attribute of `col` when the parent component is `TableHead` to identify the header cell is a header for a column.
`stackedClassName`	`string`		Additional classes to be added to the stacked Title element.
`stackedTitle`	`string`		Table data cell's corresponding header title, this stacked title is displayed as the row header when a responsive table is vertically stacked.

Guidance

When to use

When you need tabular information, such as statistical data.
When users need to compare sets of information.

When to consider alternatives

Depending on the type of content, consider using other presentation formats such as definition lists or hierarchical lists.
If you're writing out name / value pairs, there's often a more compact way compared to using a table.

Usage

Right-align numerical data in tables. You can use the align prop on the TableCell to accomplish this. Right alignment makes it easier to scan and compare numerical values.

Accessibility

Tables can have two levels of headers. Each header cell should have scope="col" or scope="row". Learn more about the "scope" attribute.
Complex tables are tables with more than two levels of headers. Each header should be given a unique id and each data cell should have a headers attribute with each related header cell’s id listed.
When adding a title to a table, include it in a <caption> tag inside of the <table> element.

Customization

The following Sass variables can be overridden to customize Table components:

Variable	Default Core Theme Value
`$table__padding`	`16px`
`$table__border-color`	`$color-black`
`$table-header__background-color`	`$color-gray-lightest`
`$table-striped__background-color`	`$color-gray-lightest`
`$table-striped-header__background-color`	`$color-gray-lightest`

Table with multi headers and a caption

<Table>

Scrollable Table

Stackable Table

Table Props

<TableCaption>

Table Caption Props

<TableHead>

Table Head Props

<TableBody>

Table Body Props

<TableRow>

Table Row Props

<TableCell>

Table Cell Props

Guidance

When to use

When to consider alternatives

Usage

Accessibility

Customization

Learn more

`<Table>`

`<TableCaption>`

`<TableHead>`

`<TableBody>`

`<TableRow>`

`<TableCell>`