Table API

Import

Cimpress UI exports multiple components that you can use as building blocks to create a table. Listed below are basic components you’ll need for most tables:

Table: a wrapper component for the entire table
TableHeader: a wrapper component for all column headers
TableHeaderRow: renders a single row within TableHeader
TableHeaderCell: renders a single column header within TableHeaderRow
TableBody: a wrapper component for all data rows
TableBodyRow: renders a single row within TableBody
TableBodyCell: renders a single cell within TableBodyRow
TableContainer: a scrollable container that allows tables to overflow in a responsive way
TableEmptyState: a special table cell that can be displayed when the table has no data

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

Building a table

Please follow our table guide to learn how to build tables with Cimpress UI components.

Accessibility notes

Table follows the ARIA grid pattern. See the linked page for a list of available keyboard interactions.

Table is a single tab stop within the page’s tab order. Use the Tab key to navigate to the table, and the arrow keys to navigate between cells.

Table requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

Table has additional accessibility considerations depending on presented data and available interactions. Please follow our table guide when building your table to make sure it’s accessible to all users.

Interactive cell content

Tables with interactive cell content should follow the rules below:

Don’t mix interactive and non-interactive content within a single cell.
Don’t use interactive controls that require arrow keys for basic operation (text fields, radio groups, etc.).
- This restriction doesn’t apply to collapsible lists hidden behind a trigger (selects, menus, etc.).

Certain screen readers, like NVDA and VoiceOver, don’t fully support the ARIA grid pattern. Users of these screen readers may experience difficulties navigating tables with interactive content.

API reference

TableContainer

Renders a scrollable container that allows a table to overflow in a responsive way.

See table usage guidelines and table building guide.

ref Ref<HTMLDivElement>: The ref type for this component.

TableContainerProps

children * ReactNode: The contents of the container.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label string: Defines a string value that labels the current element.
aria-labelledby string: Identifies the element (or elements) that labels the current element.
aria-describedby string: Identifies the element (or elements) that describes the object.
aria-details string: Identifies the element (or elements) that provide a detailed, extended description for the object.

StyleProps

margin Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Table

Displays data in an organized, tabular way.

See table usage guidelines and table building guide.

ref Ref<HTMLTableElement>: The ref type for this component.

TableProps

children * ReactNode: The contents of the table.
totalRowCount number: The number of rows in the full dataset, including headers.

Provide this value if your table presents a subset of rows, such as when using pagination. Use -1 if the number of rows is not known.

You must provide rowNumber on each table row if totalRowCount is defined.
totalColumnCount number: The number of columns in the full dataset.

Provide this value if your table presents a subset of columns, such as when the user toggles column visibility. Use -1 if the number of columns is not known.

You must provide columnNumber on each table header cell if totalColumnCount is defined.
rowSelectionMode RowSelectionMode: The type of row selection that is allowed within the table.

Defaults to 'none' .
areAllRowsSelected boolean: Whether all of the table's rows are selected. The meaning of "all rows" is dictated by the consumer.
areSomeRowsSelected boolean: Whether some (but not all) of the table's rows are selected. The meaning of "some rows" is dictated by the consumer.
onAllRowsSelectionToggle (value?: boolean) => void: A function called when the selection state of all rows should change.

If called without an argument, you are free to pick the new selection state based on your own logic. If called with an argument, you must set the selection state to the provided value.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label string: Defines a string value that labels the current element.
aria-labelledby string: Identifies the element (or elements) that labels the current element.
aria-describedby string: Identifies the element (or elements) that describes the object.
aria-details string: Identifies the element (or elements) that provide a detailed, extended description for the object.

TableHeader

Renders a header section within a table.

See table usage guidelines and table building guide.

ref Ref<HTMLTableSectionElement>: The ref type for this component.

TableHeaderProps

children * ReactNode: The header rows that belong to this table header.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

TableHeaderRow

Renders a row within a table header.

See table usage guidelines and table building guide.

ref Ref<HTMLTableRowElement>: The ref type for this component.

TableHeaderRowProps

children * ReactNode

The header cells that belong to this header row.

rowNumber number

The row's position within the full dataset, including headers.

Provide this value if your table presents a subset of rows, such as when using pagination.

This number must be:

greater than or equal to 1
greater than the rowNumber of any previous rows
less than or equal to the totalRowCount of the parent Table

Use together with totalRowCount on the Table component.

id string

The element's unique identifier. See MDN.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

UNSAFE_className string

Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.

UNSAFE_style CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

TableHeaderCell

Renders a header cell within a table header row.

See table usage guidelines and table building guide.

ref Ref<HTMLTableCellElement>: The ref type for this component.

TableHeaderCellProps

children * ReactNode

The contents of the header cell.

columnKey * string

A unique identifier for the column that this cell belongs to. Cells that belong to the same column must have the same columnKey.

columnNumber number

The position of the column that this cell belongs to within the full dataset.

Provide this value if your table presents a subset of columns, such as when the user toggles column visibility.

This number must be:

greater than or equal to 1
greater than the columnNumber of any previous cells in the current row
less than or equal to the totalColumnCount of the parent Table

Use together with totalColumnCount on the Table component.

columnWidth string | number

The width of the column. Can be any valid value of the width CSS property.

columnContentAlignment ColumnContentAlignment

Horizontal alignment of cell content within the column.

Defaults to 'start' .

sortOrder TableColumnSortOrder

The current sort order of the column.

onSortOrderToggle () => void

A function called when the column's sort order should change. If not provided, the column will not be sortable.

iconStart ReactNode

An icon displayed before the header text.

iconEnd ReactNode

An icon displayed after the header text.

id string

The element's unique identifier. See MDN.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

UNSAFE_className string

Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.

UNSAFE_style CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

TableBody

Renders a body section within a table.

See table usage guidelines and table building guide.

ref Ref<HTMLTableSectionElement>: The ref type for this component.

TableBodyProps

children * ReactNode: The rows that belong to this table body.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

TableBodyRow

Renders a row within a table body.

See table usage guidelines and table building guide.

ref Ref<HTMLTableRowElement>: The ref type for this component.

TableBodyRowProps

children * ReactNode

The cells that belong to this row.

rowNumber number

The row's position within the full dataset, including headers.

Provide this value if your table presents a subset of rows, such as when using pagination.

This number must be:

greater than or equal to 1
greater than the rowNumber of any previous rows
less than or equal to the totalRowCount of the parent Table

Use together with totalRowCount on the Table component.

isSelected boolean

Whether the row is selected.

This value will be ignored if rowSelectionMode on the Table component is set to 'none'.

onSelectionToggle (value?: boolean) => void

A function called when the row's selection state should change.

If called without an argument, you are free to pick the new selection state based on your own logic. If called with an argument, you must set the selection state to the provided value.

id string

The element's unique identifier. See MDN.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

UNSAFE_className string

Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.

UNSAFE_style CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

TableBodyCell

Renders a cell within a table body row.

See table usage guidelines and table building guide.

ref Ref<HTMLTableCellElement>: The ref type for this component.

TableBodyCellProps

children * ReactNode: The contents of the cell.
columnKey * string: A unique identifier for the column that this cell belongs to. Cells that belong to the same column must have the same columnKey.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

TableEmptyState

Renders an empty state within a table that has no data.

See table usage guidelines and table building guide.

ref Ref<HTMLTableCellElement>: The ref type for this component.

TableEmptyStateProps

title * string: The title of the empty state.
description * string: The description of the empty state.
action ReactNode: An optional action button displayed within the empty state.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.