Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System

What's new?

View code on GitHub

Table

Tables show tabular data in columns and rows.

Examples

Table with multi headers and a caption

Scrollable Table

Stackable Table

Code

React

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.

React Properties Documentation
NameTypeDefaultDescription
borderlessboolean

Applies the borderless variation of the table.

childrenrequiredReact.ReactNode

The table contents, usually TableCaption, TableHead and TableBody.

classNamestring

Additional classes to be added to the root table element.

compactboolean

Applies the compact variation of the table.

scrollableboolean

Applies a horizontal scrollbar and scrollable notice on TableCaption when the Table's contents exceed the container width.

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

stackableboolean

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.

stripedboolean

A striped variation of the table.

warningDisabledboolean

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> component

TableCaption renders the <caption> element.

React Properties Documentation
NameTypeDefaultDescription
childrenReact.ReactNode

The table caption contents.

classNamestring

Additional classes to be added to the caption element.

<TableHead> component

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

React Properties Documentation
NameTypeDefaultDescription
childrenReact.ReactNode

The table head contents, usually TableRow.

<TableBody> component

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

React Properties Documentation
NameTypeDefaultDescription
childrenReact.ReactNode

The table body contents, usually TableRow.

<TableRow> component

TableRow renders a <tr> element.

React Properties Documentation
NameTypeDefaultDescription
childrenReact.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.

React Properties Documentation
NameTypeDefaultDescription
align'center' | 'left' | 'right''left'

Set the text-align on the table cell content. Options: left, center, right.

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

classNamestring

Additional classes to be added to the row element.

headersstring

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.

idstring

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.

stackedClassNamestring

Additional classes to be added to the stacked Title element.

stackedTitlestring

Table data cell's corresponding header title, this stacked title is displayed as the row header when a responsive table is vertically stacked.

Styles

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

Sass variables for table
VariableDefault Core Theme Value
$table__padding16px
$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

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.

Learn more

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete

  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Complete

  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete

  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete

  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete

  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete

  • Spanish translations

    Includes Spanish translations for default text content.
    Not applicable

Tokens

  • Code

    Tokens implemented in code.
    Complete

  • Design

    Tokens implemented in the Sketch.
    Complete

On this page

Have ideas?