Table usage guidelines

Data tables allow users to view and manage data in an organized way.

When to use

• To present structured, comparable data in an easy-to-view grid format.
• When users need to scan, sort, or analyze multiple data points efficiently.
• For datasets where features such as sorting, filtering, or pagination are beneficial.
• To display relationships between multiple columns and rows of information.

When not to use

• When presenting only a small amount of data that can be shown as a list or card layout.
• When creating a browsing experience where the user may not know what they’re looking for or are discovering new data. For this, consider using cards instead.
• If the data benefits from progressive disclosure or is difficult to show in a row and column format. For this consider using disclosures instead.
• When displaying hierarchical data that fits better in a tree.

Usage

Preview

Title	Release year	Rating
The Shawshank Redemption	1994	⭐️ 9.3
The Godfather	1972	⭐️ 9.2
The Godfather: Part II	1974	⭐️ 9.0
The Dark Knight	2008	⭐️ 9.0
12 Angry Men	1957	⭐️ 8.9
Schindler's List	1993	⭐️ 8.9
The Lord of the Rings: The Return of the King	2003	⭐️ 8.9
Pulp Fiction	1994	⭐️ 8.9
The Lord of the Rings: The Fellowship of the Ring	2001	⭐️ 8.8
Forrest Gump	1994	⭐️ 8.8

Toggle sort order of column:

Code

import {
  Table,
  TableBody,
  TableBodyCell,
  TableBodyRow,
  TableContainer,
  TableHeader,
  TableHeaderCell,
  TableHeaderRow,
} from '@cimpress-ui/react';

const movies = [
  { title: 'The Shawshank Redemption', releaseYear: 1994, rating: 9.3 },
  { title: 'The Godfather', releaseYear: 1972, rating: 9.2 },
  { title: 'The Godfather: Part II', releaseYear: 1974, rating: 9.0 },
  { title: 'The Dark Knight', releaseYear: 2008, rating: 9.0 },
  { title: '12 Angry Men', releaseYear: 1957, rating: 8.9 },
  { title: "Schindler's List", releaseYear: 1993, rating: 8.9 },
  { title: 'The Lord of the Rings: The Return of the King', releaseYear: 2003, rating: 8.9 },
  { title: 'Pulp Fiction', releaseYear: 1994, rating: 8.9 },
  { title: 'The Lord of the Rings: The Fellowship of the Ring', releaseYear: 2001, rating: 8.8 },
  { title: 'Forrest Gump', releaseYear: 1994, rating: 8.8 },
];

export default function Demo() {
  return (
    <TableContainer>
      <Table aria-label="Movies">
        <TableHeader>
          <TableHeaderRow>
            <TableHeaderCell columnKey="title">Title</TableHeaderCell>
            <TableHeaderCell columnKey="release-year" columnContentAlignment="end">
              Release year
            </TableHeaderCell>
            <TableHeaderCell columnKey="rating" columnContentAlignment="end">
              Rating
            </TableHeaderCell>
          </TableHeaderRow>
        </TableHeader>
        <TableBody>
          {movies.map((movie) => (
            <TableBodyRow key={movie.title}>
              <TableBodyCell columnKey="title">{movie.title}</TableBodyCell>
              <TableBodyCell columnKey="release-year">{movie.releaseYear}</TableBodyCell>
              <TableBodyCell columnKey="rating">
                <span aria-hidden>⭐️ </span>
                {movie.rating.toFixed(1)}
              </TableBodyCell>
            </TableBodyRow>
          ))}
        </TableBody>
      </Table>
    </TableContainer>
  );
}

Formatting and layout

Placement

Ensure tables are placed with enough space that the table and the UI aren’t crowded. If the table has a large number of rows or columns, it should be the focal point of the UI and should not be crammed into a space it does not fit. For tables with many columns or an unpredictable number of columns, horizontal scrolling can be used to manage space on the page.

Cell content

Cells can contain either plain text, text links, or other components. Each cell should only contain one type of content - that is, all content within a cell should be either interactive or non-interactive, and never a mix of both.

Cells that use other components like badges and actions should use the small size for that component.

Cell alignment

Cell content type should always be aligned consistently:

• Left-align text content
• Right-align numerical data
• Center-align status indicators, badges, and action buttons

Do

Product	Total orders	Status
T-shirt	52	Active
Banner	115	Active

Toggle sort order of column:

Row actions

Rows can contain actions that affect only that single row. The actions column should always be the right-most column in the table, and the actions in the column should be consistent across each row. There are several ways of achieving actions in rows:

• Single action: if there is only one action the user can take, use a single button.
• 2-3 actions: if there are 2-3 actions, icon buttons can be used to display all the actions together. This should only be used for actions that have clear and common icons like “edit”, “delete”, and “view”.
• 3+ actions and complex actions: a menu is used if there are more than three actions, or if the actions do not have an obvious and common icon and would be more clear when written out with a label.

Do

Product	Total orders	Status	Single button
T-shirt	52	Active	Test product
Banner	115	Active	Test product

Toggle sort order of column:

Do

Product	Total orders	Status	Icon buttons
T-shirt	52	Active
Banner	115	Active

Toggle sort order of column:

Do

Product	Total orders	Status	Menu
T-shirt	52	Active
Banner	115	Active

Toggle sort order of column:

Column sorting

Column headers in the table component have sort functionality built in. Use this for sorting tables by columns, and avoid adding additional sort actions outside of the table.

Pagination alignment

Pagination is useful to keep tables easily readable for users when there are large data sets. Generally tables should show 10 rows per page and provide pagination so that users can easily understand the data in the table. If a table contains predictable and static data, more than 10 rows can be shown, but if the number of rows is unpredictable or the table will become excessively long, pagination should be used. For large data sets it can be helpful to allow users to select how many rows per page they would like to see. For this use a select that is left-aligned with the bottom of the table.

Do

Title	Release date	Label	Chart position
Album #1	July 8, 1997	Interscope	1000
Album #2	July 8, 1998	Universal	999
Album #3	July 8, 1999	Interscope	998
Album #4	July 8, 2000	Universal	997
Album #5	July 8, 2001	Interscope	996
Album #6	July 8, 2002	Universal	995
Album #7	July 8, 2003	Interscope	994
Album #8	July 8, 2004	Universal	993
Album #9	July 8, 2005	Interscope	992
Album #10	July 8, 2006	Universal	991

Toggle sort order of column:

Per page

10

• 1
• 2
• 3
• 4
• …
• 99
• 100

Infinite scrolling

Infinite scrolling should not be used for tables. Using pagination gives users better control when they are navigating the data and it gives them a more comprehensive view of the data set so they are not endlessly scrolling.

Filter alignment

For simple table filtering and searching, actions should be placed above the table. These filters should be directly connected to the table columns and provide simple selections on the most important columns.

Tables with many filters or complex filters should use a more advanced filtering experience. This is often achieved in a sidebar or a drawer.

Batch and table action alignment

Batch actions or other table-level actions (like creating a new row) should be placed above the table. At most only one primary button should be used for table-level actions.

Content writing

Headers

• Use clear, concise labels for each column and limit the header length to no more than a few words (for example “Status” instead of “Current status of order”).
• Headers can have an icon either before or after the text. Icons should only be used where they provide additional and new context or information rather than as a supplemental representation of the written header text.

Cells

• Keep cell content as concise as possible.
• Cells should only contain one type of content. That is, all content within a cell should be either interactive or non-interactive, and never a mix of both.

Behaviors

Empty states

Empty tables should always display a title and a description explaining that there is no data to show, and what the user can do to fix the issue. There are a few reasons why a user may encounter an empty table but most commonly, they encounter this pattern because there is no data or because of user selections.

No data

If the table is empty because there is truly no data to show, always explain why there isn’t any data. If the data is user-generated, provide a call-to-action to create or add new data.

Do

Product	Total orders	Status
No products yetYour products will show up here. Create your first product to get started. Create product

Toggle sort order of column:

User selections

Sometimes when searching, filtering, or making other selections, there might not be any data that matches the user’s parameters. When this happens, an empty state should be shown to indicate that their parameters are too restrictive.

Do

Product	Total orders	Status
No products matched your filtersTry adjusting or clearing your filters to find products. Clear filters

Toggle sort order of column: