Table | Calcite Design System

Table and related components Table Row, Table Header, and Table Cell provide a way to organize and present tabular data or content.

Overview

Table should be used to present tabular data, content, or information to a user.

Sample

Usage

Display tabular data to a user
Organize content by row and column

Best Practices

Table is an effective way of organizing complex data and content that may have many dimensions. For less complex displays of content collections that do not require row and column relationships, consider List.

Recommendations

It is important to slot Table Rows into the appropriate "table-header" or "table-footer" slot. Doing so ensures assistive technologies can accurately associate cells and their related context. While the "table-header" and "table-footer" slots are not required, Table Rows should be slotted appropriately when used.

Selection modes

Table offers "single" and "multiple" selectionMode values in addition to the default of "none". When enabled, Table displays the current number of selected Table Rows to a user, along with an affordance to clear their selection.

When selectionMode is not "none", the "selection-actions" slot will display alongside the provided selection interface. When used with pageSize, selected rows that are no longer in view will be indicated to a user.

Do use selectionMode when there are associated actions or workflows.

Do use selectionMode when displaying Table Rows that represent selectable entities a user may take action on.

Avoid using selectionMode when there are no associated user interactions.

Avoid using selectionMode with complex rowSpan and colSpan configurations.

Selection displays

When selectionMode is not "none", and selectionDisplay is "top" (the default configuration) - the Table component provides visual affordances for selection count and clearing selection to the user. When in this default display, the selection-actions slot can be useful to populate with related contextual actions.

There are times when this selectionDisplay and associated content slot may not be desirable; when applicable, the selectionDisplay property can be set to "none". This configuration can be useful where the selection count and clear selection affordances are not needed, such as when Tables contain a known and small number of rows, or when an interface should not allow a user to clear a selection. It can also facilitate the creation of alternative or unique selection interfaces for specific use cases.

Pagination

Enable pagination by providing a pageSize. When enabled, Table Rows slotted into the "table-header" or "table-footer" slot will remain visible to a user, while Table Rows slotted into the default slot are paginated.

When used with selectionMode other than "none", selected rows that are no longer in view will be indicated to a user.

Do use pageSize when there may be a large or overwhelming number of Table Rows.

Do use a pageSize of reasonable length.

Avoid using pageSize when there is an expectedly low number of Table Rows.

Avoid using an overly large pageSize value.

Note

The component offers an option for built-in pagination. However, at this time it does not provide lazy loading or virtualization. Calcite hopes to add more methods of providing data to the component in the future.

Accessibility

Key	Function
`Arrow down`	Navigates to a `calcite-table-cell` or `calcite-table-header` in the next `calcite-table-row`.
`Arrow up`	Navigates to a `calcite-table-cell` or `calcite-table-header` in the previous `calcite-table-row`.
`Page Up`	Navigates to a `calcite-table-cell` or `calcite-table-header` in the first visible `calcite-table-row`.
`Page Down`	Navigates to a `calcite-table-cell` or `calcite-table-header` in the last visible `calcite-table-row`.
`Home`	Navigates to the first `calcite-table-cell` or `calcite-table-header` in the current `calcite-table-row`.
`End`	Navigates to the last `calcite-table-cell` or `calcite-table-header` in the current `calcite-table-row`.
`Control` and `Home`	Navigates to the first `calcite-table-cell` or `calcite-table-header` in the first `calcite-table-row`.
`Control` and `End`	Navigates to the last `calcite-table-cell` or `calcite-table-header` in the last `calcite-table-row`.

API reference

Properties

Property	Attribute	Description	Type	Default
bordered	bordered	When `true`, displays borders between `calcite-table-rows`.	`boolean`	`false`
captionrequired	caption	Specifies an accessible title for the component.	`string`
currentPage	current-page	Sets/gets the current page	`number`	`0`
groupSeparator	group-separator	When `true`, number values are displayed with a group separator corresponding to the language and country format.	`boolean`	`false`
interactionMode	interaction-mode	When `"interactive"`, allows focus and keyboard navigation of `table-header`s and `table-cell`s. When `"static"`, prevents focus and keyboard navigation of `table-header`s and `table-cell`s when assistive technologies are not active. Selection affordances and slotted content within `table-cell`s remain focusable.	`TableInteractionMode`	`"interactive"`
layout	layout	Specifies the layout of the component.	`TableLayout`	`"auto"`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
numbered	numbered	When `true`, displays the position of the row in numeric form.	`boolean`	`false`
numberingSystem	numbering-system	Specifies the Unicode numeral system used by the component for localization.	`NumberingSystem \| undefined`
pageSize	page-size	Specifies the page size of the component. When present, renders `calcite-pagination`.	`number`	`0`
scale	scale	Specifies the component's size.	`Scale`	`"m"`
selectedItemsread-only		Specifies the component's selected items.	`TableRow[]`
selectionDisplay	selection-display	When `selectionMode` is `"single"` or `"multiple"`, specifies the display of the selection interface. When `selectionMode` is `"none"`, content slotted in the `selection-actions` slot will not be displayed.	`TableSelectionDisplay`	`"top"`
selectionMode	selection-mode	Specifies the selection mode of the component, where: `"multiple"` allows any number of selections, `"single"` allows only one selection, and `"none"` does not allow any selections.	`Extract<"none" \| "multiple" \| "single", SelectionMode>`	`"none"`
striped	striped	When `true`, displays striped styling on the component's `calcite-table-rows`.	`boolean`	`false`

Slots

Name	Description
default (unnamed)	A slot for adding `calcite-table-row` elements containing `calcite-table-cell` and/or `calcite-table-header` elements.
table-header	A slot for adding `calcite-table-row` elements containing `calcite-table-header` elements.
table-footer	A slot for adding `calcite-table-row` elements containing `calcite-table-cell` and/or `calcite-table-header` elements.
selection-actions	A slot for adding `calcite-actions` or other elements to display when `selectionMode` is not `"none"` and `selectionDisplay` is not `"none"`.

Styles

Name	Description
--calcite-table-border-color	Specifies the component's border color.
--calcite-table-corner-radius	Specifies the component's border radius.
--calcite-table-shadow	Specifies the component's shadow.
--calcite-table-number-cell-background-color	Specifies the background color of the component's `numbered` cell.
--calcite-table-number-cell-text-color	Specifies the text color of the component's `numbered` cell.
--calcite-table-selection-cell-background-color	When `selectionMode` is `"multiple"` or `"single"`, specifies the background color of cells containing selection icons.
--calcite-table-selection-cell-background-color-selected	When `selectionMode` is `"multiple"` or `"single"`, specifies the background color of cells containing selection icons on `selected` `calcite-table-row`s.
--calcite-table-selection-cell-icon-color	When `selectionMode` is `"multiple"` or `"single"`, specifies the icon color of the component's selection icon on `calcite-table-row`s where `selected` is `false`.
--calcite-table-selection-cell-icon-color-selected	When `selectionMode` is `"multiple"` or `"single"`, specifies the icon color of the component's selection icon on `selected` `calcite-table-row`s.
--calcite-table-selection-chip-background-color	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are not `selected`, specifies the background color of the component's selection chip.
--calcite-table-selection-chip-border-color	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are not `selected`, specifies the border color of the component's selection chip.
--calcite-table-selection-chip-corner-radius	When `selectionMode` is `"multiple"` or `"single"`, specifies the corner radius of the component's selection chip.
--calcite-table-selection-chip-shadow	When `selectionMode` is `"multiple"` or `"single"`, specifies the shadow of the component's selection chip.
--calcite-table-selection-chip-text-color	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are not `selected`, specifies the text color of the component's selection chip.
--calcite-table-selection-chip-background-color-selected	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the background color of the component's selection chip.
--calcite-table-selection-chip-border-color-selected	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the border color of the component's selection chip.
--calcite-table-selection-chip-text-color-selected	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the text color of the component's selection chip.
--calcite-table-selection-out-of-view-chip-background-color	When `selectionMode` is `"multiple"` or `"single"`, `pageSize` is set, and `calcite-table-row`s are `selected` on non-current pages, specifies the background color of the component's selection out of view chip.
--calcite-table-selection-out-of-view-chip-border-color	When `selectionMode` is `"multiple"` or `"single"`, `pageSize` is set, and `calcite-table-row`s are `selected` on non-current pages, specifies the border color of the component's selection out of view chip.
--calcite-table-selection-out-of-view-chip-corner-radius	When `selectionMode` is `"multiple"` or `"single"`, `pageSize` is set, and `calcite-table-row`s are `selected` on non-current pages, specifies the corner radius of the component's selection out of view chip.
--calcite-table-selection-out-of-view-chip-icon-color	When `selectionMode` is `"multiple"` or `"single"`, `pageSize` is set, and `calcite-table-row`s are `selected` on non-current pages, specifies the icon color of the component's selection out of view chip.
--calcite-table-selection-out-of-view-chip-shadow	When `selectionMode` is `"multiple"` or `"single"`, `pageSize` is set, and `calcite-table-row`s are `selected` on non-current pages, specifies the shadow of the component's selection out of view chip.
--calcite-table-selection-out-of-view-chip-text-color	When `selectionMode` is `"multiple"` or `"single"`, `pageSize` is set, and `calcite-table-row`s are `selected` on non-current pages, specifies the text color of the component's selection out of view chip.
--calcite-table-selection-dismiss-button-background-color-active	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the background color of the component's selection dismiss chip when active.
--calcite-table-selection-dismiss-button-background-color-hover	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the background color of the component's selection dismiss chip when hovered.
--calcite-table-selection-dismiss-button-background-color	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the background color of the component's selection dismiss chip.
--calcite-table-selection-dismiss-button-border-color-active	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the border color of the component's selection dismiss chip when active.
--calcite-table-selection-dismiss-button-border-color-hover	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the border color of the component's selection dismiss chip when hovered.
--calcite-table-selection-dismiss-button-border-color	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the border color of the component's selection dismiss chip.
--calcite-table-selection-dismiss-button-corner-radius	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the corner radius of the component's selection dismiss chip.
--calcite-table-selection-dismiss-button-shadow	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the shadow of the component's selection dismiss chip.
--calcite-table-selection-dismiss-button-text-color-active	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the text color of the component's selection dismiss chip when active.
--calcite-table-selection-dismiss-button-text-color-hover	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the text color of the component's selection dismiss chip when hovered.
--calcite-table-selection-dismiss-button-text-color	When `selectionMode` is `"multiple"` or `"single"` and `calcite-table-row`s are `selected`, specifies the text color of the component's selection dismiss chip.
--calcite-table-pagination-color	When `pageSize` is set, specifies the component's pagination item color.
--calcite-table-pagination-color-hover	When `pageSize` is set, specifies the component's pagination item color when hovered or selected.
--calcite-table-pagination-color-border-hover	When `pageSize` is set, specifies the component's pagination item bottom border color when hovered.
--calcite-table-pagination-color-border-active	When `pageSize` is set, specifies the component's pagination item bottom border color when selected.
--calcite-table-pagination-background-color	When `pageSize` is set, specifies the component's pagination item background color when active.
--calcite-table-pagination-icon-color-background-hover	When `pageSize` is set, specifies the component's pagination chevron item background color when hovered.

Events

Name	Description	Behavior
calciteTablePageChange	Emits when the component's page selection changes.	bubblescomposed
calciteTableSelect	Emits when the component's selected rows change.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`