Skip to content
Cimpress UI

Tables

Tables can be used to present users with interactive tabular information. A table can be a simple listing with 3-4 columns, but it can also be a highly interactive widget that allows users to select rows, hide and/or sort columns, and perform custom row actions. Because of this complexity, Cimpress UI doesn’t provide a single all-encompassing table component. Instead, it provides building blocks that allow you to build your own table that’s tailored to the needs of your application and your dataset.

This guide will show you how to build your own table from Cimpress UI building blocks, and will walk you through any additional considerations for making your table accessible to more people.

Data source

Section titled “Data source”

Cimpress UI doesn’t assume anything about your data source. Our components help you display the data and all necessary controls, but they don’t contain any data logic. It’s up to you to modify your data based on actions performed by users.

While you can wire up a simple table by yourself using React state, we recommend using a headless data engine for more complex scenarios. Such an engine handles all state and interactions for you.

We recommend using TanStack Table as your data engine. We also provide the @cimpress-ui/tanstack-table-react package, which contains a set of components and hooks that seamlessly connect TanStack Table with Cimpress UI components.

To use this package, install it as a dependency in your application alongside Cimpress UI:

Terminal window
npm install @cimpress-ui/tanstack-table-react

You do not need to install TanStack Table separately. All exports from @tanstack/react-table are re-exported from @cimpress-ui/tanstack-table-react/base.

Prerequisites

Section titled “Prerequisites”

We are going to build a table showcasing the highest-rated movies. This is what our data looks like:

data.ts
export interface Movie {
  title: string;
  releaseYear: number;
  rating: number;
}


export const movies: Movie[] = [
  { 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 },
];

Additionally, we’ll need a React component to render our table:

table.tsx
export function MovieTable() {
  return 'This will be a table';
}

Basic data table

Section titled “Basic data table”

First, let’s build a simple table with no interactivity. Choose the “Manual” or “TanStack” tab, depending on how you intend to build your table.

  1. Build a basic table structure using Cimpress UI components. Don’t forget to label your table!

    table.tsx
    import { Table, TableBody, TableContainer, TableHeader } from '@cimpress-ui/react';
    

    export function MovieTable() {
      return 'This will be a table';
      return (
        <TableContainer>
          <Table aria-label="Highest-rated movies">
            <TableHeader />
            <TableBody />
          </Table>
        </TableContainer>
      );
    }

  2. Add a header row based on your data structure. Make sure that each header cell has a unique columnKey.

    table.tsx
    import { Table, TableBody, TableContainer, TableHeader } from '@cimpress-ui/react';
    import { Table, TableBody, TableContainer, TableHeader, TableHeaderCell, TableHeaderRow } from '@cimpress-ui/react';
    

    export function MovieTable() {
      return (
        <TableContainer>
          <Table aria-label="Highest-rated movies">
            <TableHeader />
            <TableHeader>
              <TableHeaderRow>
                <TableHeaderCell columnKey="title">Title</TableHeaderCell>
                <TableHeaderCell columnKey="release-year">Release year</TableHeaderCell>
                <TableHeaderCell columnKey="rating">Rating</TableHeaderCell>
              </TableHeaderRow>
            </TableHeader>
            <TableBody />
          </Table>
        </TableContainer>
      );
    }

  3. Map over your data to create table rows. Make sure that each body cell has a columnKey that’s the same as the columnKey of the corresponding header cell.

    table.tsx
    import {
      Table,
      TableBody,
      TableBodyCell,
      TableBodyRow,
      TableContainer,
      TableHeader,
      TableHeaderCell,
      TableHeaderRow,
    } from '@cimpress-ui/react';
    import { movies } from './data.js';
    

    export function MovieTable() {
      return (
        <TableContainer>
          <Table aria-label="Highest-rated movies">
            <TableHeader>
              <TableHeaderRow>
                <TableHeaderCell columnKey="title">Title</TableHeaderCell>
                <TableHeaderCell columnKey="release-year">Release year</TableHeaderCell>
                <TableHeaderCell columnKey="rating">Rating</TableHeaderCell>
              </TableHeaderRow>
            </TableHeader>
            <TableBody />
            <TableBody>
              {movies.map((movie) => (
                <TableBodyRow key={movie.title}>
                  <TableBodyCell columnKey="title">{movie.title}</TableBodyCell>
                  <TableBodyCell columnKey="release-year">{movie.releaseYear}</TableBodyCell>
                  <TableBodyCell columnKey="rating">{movie.rating.toFixed(1)}</TableBodyCell>
                </TableBodyRow>
              ))}
            </TableBody>
          </Table>
        </TableContainer>
      );
    }

Column properties

Section titled “Column properties”

Let’s make our table look a little better. We’ll assign specific widths to the columns, and align the content of “Release year” and “Rating” columns to the right.

table.tsx
// ...
<TableHeader>
  <TableHeaderRow>
    <TableHeaderCell columnKey="title">Title</TableHeaderCell>
    <TableHeaderCell columnKey="title" columnWidth="60%">
      Title
    </TableHeaderCell>
    <TableHeaderCell columnKey="release-year">Release year</TableHeaderCell>
    <TableHeaderCell columnKey="release-year" columnWidth="20%" columnContentAlignment="end">
      Release year
    </TableHeaderCell>
    <TableHeaderCell columnKey="rating">Rating</TableHeaderCell>
    <TableHeaderCell columnKey="rating" columnWidth="20%" columnContentAlignment="end">
      Rating
    </TableHeaderCell>
  </TableHeaderRow>
</TableHeader>
// ...

Cell content

Section titled “Cell content”

Make sure that the information within each cell can be conveyed by a screen reader. If a cell contains decorative elements that shouldn’t be read (icons, emojis, etc.), mark them with the aria-hidden attribute.

Let’s add a star symbol to our rating column. As an example, if a cell contains the text “⭐️ 9.3”, a screen reader will read it as “star nine point three”. To make it read “nine point three”, mark the star and the space next to it with the aria-hidden attribute.

table.tsx
// ...
<TableBody>
  {movies.map((movie) => (
    <TableBodyRow key={movie.title}>
      <TableBodyCell columnKey="title">{movie.title}</TableBodyCell>
      <TableBodyCell columnKey="release-year">{movie.releaseYear}</TableBodyCell>
      <TableBodyCell columnKey="rating">{movie.rating.toFixed(1)}</TableBodyCell>
      <TableBodyCell columnKey="rating">
        <span aria-hidden>⭐️ </span>
        {movie.rating.toFixed(1)}
      </TableBodyCell>
    </TableBodyRow>
  ))}
</TableBody>
// ...

Final result

Section titled “Final result”

This is what our table looks like now. All following chapters will use this table as a starting point.

Title
Release year
Rating
The Shawshank Redemption19949.3
The Godfather19729.2
The Godfather: Part II19749.0
The Dark Knight20089.0
12 Angry Men19578.9
Schindler's List19938.9
The Lord of the Rings: The Return of the King20038.9
Pulp Fiction19948.9
The Lord of the Rings: The Fellowship of the Ring20018.8
Forrest Gump19948.8

Working with partial data

Section titled “Working with partial data”

There are situations when your table can present partial data, such as when using pagination, or when not all columns are visible on the page. While this is usually obvious for sighted users based on the presence of additional UI controls, screen reader users may find it hard to orient themselves within such a table. To alleviate this, you should provide some additional information to table components.

Subset of rows

Section titled “Subset of rows”

If your table presents a subset of rows from a larger dataset (such as when using pagination), you should provide the following additional information:

  • The number of rows in the full unpaginated dataset, including headers.
  • The position of each row within the full unpaginated dataset, including headers.

Let’s paginate our table, displaying 3 rows per page:

  1. Define variables required for pagination.

    table.tsx
    // ...
    const pageSize = 3;
    const pageCount = Math.floor(movies.length / 3) + 1;
    

    export function MovieTable() {
      const [currentPage, setCurrentPage] = useState(1);
      const [data, setData] = useState<Movie[]>(() => movies.slice(0, pageSize));
    

      return (
        <TableContainer>
          <Table aria-label="Highest-rated movies">
            <TableHeader>
              <TableHeaderRow>
                // ...
              </TableHeaderRow>
            </TableHeader>
            <TableBody>
              {movies.map((movie) => (
              {data.map((movie) => (
                <TableBodyRow key={movie.title}>
                  // ...
                </TableBodyRow>
              ))}
            </TableBody>
          </Table>
        </TableContainer>
      );
    }

  2. Add a pagination component. Don’t forget to link it with the table so that screen readers can recognize the relationship.

    table.tsx
    // ...
    const pageSize = 3;
    const pageCount = Math.floor(movies.length / 3) + 1;
    

    export function MovieTable() {
      const [currentPage, setCurrentPage] = useState(1);
      const [data, setData] = useState<Movie[]>(() => movies.slice(0, pageSize));
    

      const handlePageChange = (page: number) => {
        setCurrentPage(page);
        setData(movies.slice((page - 1) * pageSize, page * pageSize));
      };
    

      return (
        <Stack gap={16}>
          <TableContainer>
            <Table aria-label="Highest-rated movies">
            <Table id="movie-table" aria-label="Highest-rated movies">
              <TableHeader>
                <TableHeaderRow>
                  // ...
                </TableHeaderRow>
              </TableHeader>
              <TableBody>
                {data.map((movie) => (
                  <TableBodyRow key={movie.title}>
                    // ...
                  </TableBodyRow>
                ))}
              </TableBody>
            </Table>
          </TableContainer>
    

          <Pagination
            aria-label="Table pagination"
            paginatedElementId="movie-table"
            pageCount={pageCount}
            currentPage={currentPage}
            onPageChange={handlePageChange}
          />
        </Stack>
      );
    }

  3. Provide totalRowCount and rowNumber props. Make sure to include header rows in the calculation. Refer to the table API reference for more information on these props.

    table.tsx
    // ...
    const pageSize = 3;
    const pageCount = Math.floor(movies.length / 3) + 1;
    

    export function MovieTable() {
      const [currentPage, setCurrentPage] = useState(1);
      const [data, setData] = useState<Movie[]>(() => movies.slice(0, pageSize));
    

      const handlePageChange = (page: number) => {
        setCurrentPage(page);
        setData(movies.slice((page - 1) * pageSize, page * pageSize));
      };
    

      return (
        <Stack gap={16}>
          <TableContainer>
            <Table id="movie-table" aria-label="Highest-rated movies">
            <Table id="movie-table" aria-label="Highest-rated movies" totalRowCount={movies.length + 1}>
              <TableHeader>
                <TableHeaderRow>
                <TableHeaderRow rowNumber={1}>
                  // ...
                </TableHeaderRow>
              </TableHeader>
              <TableBody>
                {data.map((movie) => (
                  <TableBodyRow key={movie.title}>
                  <TableBodyRow key={movie.title} rowNumber={movies.indexOf(movie) + 2}>
                    // ...
                  </TableBodyRow>
                ))}
              </TableBody>
            </Table>
          </TableContainer>
    

          <Pagination
            aria-label="Table pagination"
            paginatedElementId="movie-table"
            pageCount={pageCount}
            currentPage={currentPage}
            onPageChange={handlePageChange}
          />
        </Stack>
      );
    }

Here is how our paginated table looks like. You can verify the presence of additional row-related attributes by inspecting the DOM.

Subset of columns

Section titled “Subset of columns”

If your table presents a subset of columns from a larger dataset (such as when the user is allowed to hide columns), you should provide the following additional information:

  • The number of columns in the full dataset.
  • The position of each column within the full dataset.

Let’s hide the “Release year” column from our table:

  1. Remove the “Release year” column from the table markup.

    table.tsx
    // ...
    export function MovieTable() {
      return (
        <TableContainer>
          <Table aria-label="Highest-rated movies">
            <TableHeader>
              <TableHeaderRow>
                <TableHeaderCell columnKey="title" columnWidth="60%">
                  Title
                </TableHeaderCell>
                <TableHeaderCell columnKey="release-year" columnWidth="20%" columnContentAlignment="end">
                  Release year
                </TableHeaderCell>
                <TableHeaderCell columnKey="rating" columnWidth="20%" 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>
      );
    }

  2. Provide totalColumnCount and columnNumber props. Refer to the table API reference for more information on these props.

    table.tsx
    // ...
    export function MovieTable() {
      return (
        <TableContainer>
          <Table aria-label="Highest-rated movies">
          <Table aria-label="Highest-rated movies" totalColumnCount={3}>
            <TableHeader>
              <TableHeaderRow>
                <TableHeaderCell
                  columnKey="title"
                  columnNumber={1}
                  columnWidth="60%"
                >
                  Title
                </TableHeaderCell>
                <TableHeaderCell
                  columnKey="rating"
                  columnNumber={3}
                  columnWidth="20%"
                  columnContentAlignment="end"
                >
                  Rating
                </TableHeaderCell>
              </TableHeaderRow>
            </TableHeader>
            <TableBody>
              // ...
            </TableBody>
          </Table>
        </TableContainer>
      );
    }

Here is how our table looks like. You can verify the presence of additional column-related attributes by inspecting the DOM.

Title
Rating
The Shawshank Redemption9.3
The Godfather9.2
The Godfather: Part II9.0
The Dark Knight9.0
12 Angry Men8.9
Schindler's List8.9
The Lord of the Rings: The Return of the King8.9
Pulp Fiction8.9
The Lord of the Rings: The Fellowship of the Ring8.8
Forrest Gump8.8

No data

Section titled “No data”

It’s possible for the table to have no rows to display. This can happen when no data is available, or when the table rows are filtered. Let’s see how we can display an “empty state” in our table if needed.

Let’s assume our table of highest-rated movies has been filtered so that no rows meet the filtering criteria. We’re not going to set up the filtering itself in this guide. Instead, in order to keep things simple, we’ll assume that the movies array can be empty.

All we need to do is render the <TableEmptyState> component when there’s no rows to display, like so:

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


// ...


export function MovieTable() {
  return (
    <TableContainer>
      <Table aria-label="Highest-rated movies">
        <TableHeader>
          <TableHeaderRow>
            // ...
          </TableHeaderRow>
        </TableHeader>
        <TableBody>
          {movies.map((movie) => (
          {movies.length > 0 ? movies.map((movie) => (
            <TableBodyRow key={movie.title}>
              // ...
            </TableBodyRow>
          ))}
          )) : (
            <TableEmptyState
              title="No movies to display"
              description="Try adjusting or clearing your filters."
              action={<Button size="small">Clear filters</Button>}
            />
          )}
        </TableBody>
      </Table>
    </TableContainer>
  );
}

Here is the finished table with no data to display:

Title
Release year
Rating
No movies to displayTry adjusting or clearing your filters.

Row selection

Section titled “Row selection”

Often we want users to be able to select specific rows in a table. Cimpress UI provides building blocks for row selection functionality, but you are in control of the selection state.

  1. Define state required for row selection.

    table.tsx
    // ...
    export function MovieTable() {
      const [selectedRows, setSelectedRows] = useState<Record<number, true>>({});
      const [areAllRowsSelected, setAreAllRowsSelected] = useState(false);
    

      return (
        // ...
      );
    }

  2. Connect your state with table components.

    table.tsx
    // ...
    export function MovieTable() {
      const [selectedRows, setSelectedRows] = useState<Record<number, true>>({});
      const [areAllRowsSelected, setAreAllRowsSelected] = useState(false);
    

      return (
        <TableContainer>
          <Table aria-label="Highest-rated movies">
          <Table
            aria-label="Highest-rated movies"
            rowSelectionMode="multiple"
            areAllRowsSelected={areAllRowsSelected}
            areSomeRowsSelected={areAllRowsSelected || Object.keys(selectedRows).length > 0}
            onAllRowsSelectionToggle={(value) => setAreAllRowsSelected(value ?? !areAllRowsSelected)}
          >
            <TableHeader>
              // ...
            </TableHeader>
            <TableBody>
              {movies.map((movie, idx) => (
                <TableBodyRow key={movie.title}>
                <TableBodyRow
                  key={movie.title}
                  isSelected={areAllRowsSelected || idx in selectedRows}
                  onSelectionToggle={(value) =>
                    setSelectedRows((prev) => {
                      if ((value === undefined && prev[idx]) || value === false) {
                        delete prev[idx];
                        return { ...prev };
                      } else {
                        return { ...prev, [idx]: true };
                      }
                    })
                  }
                >
                  // ...
                </TableBodyRow>
              ))}
            </TableBody>
          </Table>
        </TableContainer>
      );
    }

  3. Add a selection column to your table, so that users have a visible indicator of which rows are selected.

    table.tsx
    import {
      Table,
      TableAllRowsSelector,
      TableBody,
      TableBodyCell,
      TableBodyRow,
      TableContainer,
      TableHeader,
      TableHeaderCell,
      TableHeaderRow,
      TableRowSelector,
    } from '@cimpress-ui/react';
    import { movies } from './data.js';
    

    export function MovieTable() {
      const [selectedRows, setSelectedRows] = useState<Record<number, true>>({});
      const [areAllRowsSelected, setAreAllRowsSelected] = useState(false);
    

      return (
        // ...
            <TableHeader>
              <TableHeaderRow>
                <TableHeaderCell columnKey="row-selector" columnWidth="0" columnContentAlignment="center">
                  <TableAllRowsSelector aria-label="Select all rows" />
                </TableHeaderCell>
                // ...
              </TableHeaderRow>
            </TableHeader>
            <TableBody>
              {movies.map((movie) => (
              {movies.map((movie, idx) => (
                <TableBodyRow
                  key={movie.title}
                  isSelected={areAllRowsSelected || idx in selectedRows}
                  onSelectionToggle={(value) =>
                    setSelectedRows((prev) => {
                      if ((value === undefined && prev[idx]) || value === false) {
                        delete prev[idx];
                        return { ...prev };
                      } else {
                        return { ...prev, [idx]: true };
                      }
                    })
                  }
                >
                  <TableBodyCell columnKey="row-selector">
                    <TableRowSelector aria-label={`Select row ${idx + 2}`} />
                  </TableBodyCell>
                  // ...
                </TableBodyRow>
              ))}
            </TableBody>
        // ...
      );
    }

Here is the finished table with selectable rows:

Title
Release year
Rating
The Shawshank Redemption19949.3
The Godfather19729.2
The Godfather: Part II19749.0
The Dark Knight20089.0
12 Angry Men19578.9
Schindler's List19938.9
The Lord of the Rings: The Return of the King20038.9
Pulp Fiction19948.9
The Lord of the Rings: The Fellowship of the Ring20018.8
Forrest Gump19948.8

Column sorting

Section titled “Column sorting”

Cimpress UI’s table header cells have sorting capabilities built-in. As with other functionalities, you are in control of the sort state.

  1. Define state required for column sorting.

    table.tsx
    import {
      Table,
      TableBody,
      TableBodyCell,
      TableBodyRow,
      TableColumnSortOrder,
      TableContainer,
      TableHeader,
      TableHeaderCell,
      TableHeaderRow,
    } from '@cimpress-ui/react';
    import { movies } from './data.js';
    

    export function MovieTable() {
      const [sortedColumnKey, setSortedColumnKey] = useState<string>('rating');
      const [sortOrder, setSortOrder] = useState<TableColumnSortOrder>('descending');
    

      return (
        // ...
      );
    }

  2. Connect your state with table components.

    table.tsx
    // ...
    export function MovieTable() {
      const [sortedColumnKey, setSortedColumnKey] = useState<string>('rating');
      const [sortOrder, setSortOrder] = useState<TableColumnSortOrder>('descending');
    

      const handleSortOrderChange = (columnKey: string) => {
        if (columnKey !== sortedColumnKey) {
          setSortedColumnKey(columnKey);
          setSortOrder('ascending');
        } else if (sortOrder === 'ascending') {
          setSortOrder('descending');
        } else {
          setSortedColumnKey('');
        }
      };
    

      return (
        <TableContainer>
          <Table aria-label="Highest-rated movies">
            <TableHeader>
              <TableHeaderRow>
                <TableHeaderCell
                  columnKey="title"
                  columnWidth="60%"
                  sortOrder={sortedColumnKey === 'title' ? sortOrder : undefined}
                  onSortOrderToggle={() => handleSortOrderChange('title')}
                >
                  Title
                </TableHeaderCell>
                <TableHeaderCell
                  columnKey="release-year"
                  columnWidth="20%"
                  columnContentAlignment="end"
                  sortOrder={sortedColumnKey === 'release-year' ? sortOrder : undefined}
                  onSortOrderToggle={() => handleSortOrderChange('release-year')}
                >
                  Release year
                </TableHeaderCell>
                <TableHeaderCell
                  columnKey="rating"
                  columnWidth="20%"
                  columnContentAlignment="end"
                  sortOrder={sortedColumnKey === 'rating' ? sortOrder : undefined}
                  onSortOrderToggle={() => handleSortOrderChange('rating')}
                >
                  Rating
                </TableHeaderCell>
              </TableHeaderRow>
            </TableHeader>
            <TableBody>
              {movies.map((movie, idx) => (
                // ...
              ))}
            </TableBody>
          </Table>
        </TableContainer>
      );
    }

Here is the finished table with sortable columns:

Title
Release year
Rating
The Shawshank Redemption19949.3
The Godfather19729.2
The Godfather: Part II19749.0
The Dark Knight20089.0
12 Angry Men19578.9
Schindler's List19938.9
The Lord of the Rings: The Return of the King20038.9
Pulp Fiction19948.9
The Lord of the Rings: The Fellowship of the Ring20018.8
Forrest Gump19948.8