Data table

Data tables are used to organize and display data efficiently. The data table component allows for customization with additional functionality, as needed by your product’s users.

Overview
Live demo
Formatting
Content
Behaviors
Modifiers
Related
Feedback

Overview

The data table’s features are ideal for organizing and displaying data in a UI. The column headers can sort data in ascending or descending order, rows can be expanded to progressively disclose information, and single or batch actions can be taken on rows.

The data table toolbar gives a location for primary buttons, search, filtering, table display settings, and other utilities.

When to use

To organize and display data.
If your user must navigate to a specific piece of data to complete a task.
Displaying all of a user’s resources.

When not to use

When a more complex display of the data or interactions are required.
As a replacement for a spreadsheet application.

Variants

Variant	Purpose
Default	The default data table comes with a base style with only the title, header, and table elements. rows.
With selection	Batch actions are functions that may be performed on multiple items within a table. This variant of table enables the user to select individual rows and apply an action. A batch action toolbar appears when table rows are selected.
With expansion	The expandable data table is useful for presenting large amounts of data in a small space. Rows are collapsed and can be expanded to reveal extra information.

Live demo

Theme selector

Variant selector

CodeSandbox React Angular Vue Vanilla Web Components

Live editor for the Default component

<DataTable rows={rowData} headers={headerData}>
  {({ rows, headers, getHeaderProps, getTableProps }) => (
    <TableContainer title="DataTable">
      <Table {...getTableProps()}>
        <TableHead>
          <TableRow>
            {headers.map((header) => (
              <TableHeader {...getHeaderProps({ header })}>
                {header.header}
              </TableHeader>
            ))}
          </TableRow>
        </TableHead>
        <TableBody>
          {rows.map((row) => (
            <TableRow key={row.id}>
              {row.cells.map((cell) => (
                <TableCell key={cell.id}>{cell.value}</TableCell>
              ))}
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </TableContainer>
  )}
</DataTable>

<DataTable rows={rowData} headers={headerData}>
  {({ rows, headers, getHeaderProps, getTableProps }) => (
    <TableContainer title="DataTable">
      <Table {...getTableProps()}>
        <TableHead>
          <TableRow>
            {headers.map((header) => (
              <TableHeader {...getHeaderProps({ header })}>
                {header.header}
              </TableHeader>
            ))}
          </TableRow>
        </TableHead>
        <TableBody>
          {rows.map((row) => (
            <TableRow key={row.id}>
              {row.cells.map((cell) => (
                <TableCell key={cell.id}>{cell.value}</TableCell>
              ))}
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </TableContainer>
  )}
</DataTable>

Formatting

Anatomy

Title and description: contains the data table title and an optional description.
Toolbar: global data table controls including search and table settings.
Column header: title for the row header with the optional sorting behavior.
Table row: can be configured to show different types of data. Rows can be selectable, expandable, and modified to show alternating zebra stripe background colors.
Pagination table bar: an optional component that lets a user navigate data as pages when the amount of data it too large to be shown at once.

Sizing

The data table is available in four different row sizes: tall, normal, short, compact.

The column header row .bx--data-table thead should always match the row size of the table. Tall row heights are only recommended if your data is expected to have 2 lines of content in a single row.

Do use the same row height for the table and header rows.

Don’t mix row heights for the table and header rows.

Two heights are available to be paired with the row heights of the data table. The tall toolbar should only be paired with the normal and tall row heights and the small toolbar should only be used with the small and compact row heights.

A small toolbar on a short data table and a tall toolbar on a normal data table

Placement

Data tables should be placed in a page’s main content area and given plenty of space to display data without truncation. Avoid placing data tables inside modals or smaller containers where the information can feel cramped or needs truncation.

The data table can be placed on the grid following the three different grid modes outlined in the 2x grid guidelines. Although, the data table can share horizontal space with other components and content, consider giving your data table the most width on the page to help your user view dense data.

These three examples show the data table on the wide (default), narrow, and condensed grid modes. Note the different type alignments and gutter sizes.

Wide grid mode

The wide grid mode is the default and gives the most breathing room between the data table and the other components or content.

Data table on a wide (default) grid

Narrow grid mode

Using the data table on a narrow grid will hang the component into the gutter and create a desirable type alignment between the the data table’s title and other type on the page.

Data table on a narrow grid

Condensed grid mode

The data table can be used on a condensed grid, but care should be taken to avoid any unintentional relationships with other UI elements. Use a hybrid grid or a dissimilar background color to avoid the components blending in to each other.

Data table on a condensed grid