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 Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

TableContainerProps

children * Section titled “ children * ” ReactNode: The contents of the container.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ 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 Section titled “ 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 Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ 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 Section titled “ ref ” Ref<HTMLTableElement>: The ref type for this component.

TableProps

children * Section titled “ children * ” ReactNode: The contents of the table.
totalRowCount Section titled “ 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 Section titled “ 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 Section titled “ rowSelectionMode ” RowSelectionMode: The type of row selection that is allowed within the table.

Defaults to 'none' .
areAllRowsSelected Section titled “ areAllRowsSelected ” boolean: Whether all of the table's rows are selected. The meaning of "all rows" is dictated by the consumer.
areSomeRowsSelected Section titled “ 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 Section titled “ 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 Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ 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 Section titled “ 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 Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ 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 Section titled “ ref ” Ref<HTMLTableSectionElement>: The ref type for this component.

TableHeaderProps

children * Section titled “ children * ” ReactNode: The header rows that belong to this table header.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ 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 Section titled “ 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 Section titled “ ref ” Ref<HTMLTableRowElement>: The ref type for this component.

TableHeaderRowProps

children * Section titled “ children * ” ReactNode

The header cells that belong to this header row.

rowNumber Section titled “ 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 Section titled “ id ” string

The element's unique identifier. See MDN.

data-cim-style-root Section titled “ data-cim-style-root ” boolean

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

UNSAFE_className Section titled “ 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 Section titled “ 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 Section titled “ ref ” Ref<HTMLTableCellElement>: The ref type for this component.

TableHeaderCellProps

children * Section titled “ children * ” ReactNode

The contents of the header cell.

columnKey * Section titled “ 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 Section titled “ 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 Section titled “ columnWidth ” string | number

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

columnContentAlignment Section titled “ columnContentAlignment ” ColumnContentAlignment

Horizontal alignment of cell content within the column.

Defaults to 'start' .

sortOrder Section titled “ sortOrder ” TableColumnSortOrder

The current sort order of the column.

onSortOrderToggle Section titled “ onSortOrderToggle ” () => void

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

iconStart Section titled “ iconStart ” ReactNode

An icon displayed before the header text.

iconEnd Section titled “ iconEnd ” ReactNode

An icon displayed after the header text.

id Section titled “ id ” string

The element's unique identifier. See MDN.

data-cim-style-root Section titled “ data-cim-style-root ” boolean

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

UNSAFE_className Section titled “ 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 Section titled “ 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 Section titled “ ref ” Ref<HTMLTableSectionElement>: The ref type for this component.

TableBodyProps

children * Section titled “ children * ” ReactNode: The rows that belong to this table body.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ 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 Section titled “ 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 Section titled “ ref ” Ref<HTMLTableRowElement>: The ref type for this component.

TableBodyRowProps

children * Section titled “ children * ” ReactNode

The cells that belong to this row.

rowNumber Section titled “ 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 Section titled “ isSelected ” boolean

Whether the row is selected.

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

onSelectionToggle Section titled “ 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 Section titled “ id ” string

The element's unique identifier. See MDN.

data-cim-style-root Section titled “ data-cim-style-root ” boolean

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

UNSAFE_className Section titled “ 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 Section titled “ 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 Section titled “ ref ” Ref<HTMLTableCellElement>: The ref type for this component.

TableBodyCellProps

children * Section titled “ children * ” ReactNode: The contents of the cell.
columnKey * Section titled “ 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 Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ 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 Section titled “ 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 Section titled “ ref ” Ref<HTMLTableCellElement>: The ref type for this component.

TableEmptyStateProps

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

See styling guide.

Table API

Import

Building a table

Accessibility notes

Interactive cell content

API reference

TableContainer

ref

children *

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

Table

ref

children *

totalRowCount

totalColumnCount

rowSelectionMode

areAllRowsSelected

areSomeRowsSelected

onAllRowsSelectionToggle

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

TableHeader

ref

children *

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

TableHeaderRow

ref

children *

rowNumber

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

TableHeaderCell

ref

children *

columnKey *

columnNumber

columnWidth

columnContentAlignment

sortOrder

onSortOrderToggle

iconStart

iconEnd

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

TableBody

ref

children *

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

TableBodyRow

ref