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" selection 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 selection is not "none", the "selection-actions" slot will display alongside the provided selection interface. When used with page, selected rows that are no longer in view will be indicated to a user.
selectionMode when there are associated actions or workflows.selectionMode when displaying Table Rows that represent selectable entities a user may take action on.selectionMode when there are no associated user interactions.selectionMode with complex rowSpan and colSpan configurations.Selection displays
When selection is not "none", and selection 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 selection and associated content slot may not be desirable; when applicable, the selection 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 page. 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 selection other than "none", selected rows that are no longer in view will be indicated to a user.
pageSize when there may be a large or overwhelming number of Table Rows.pageSize of reasonable length.pageSize when there is an expectedly low number of Table Rows.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
Keyboard navigation
| 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 |
| caption | 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-headers and table-cells. When "static", prevents focus and keyboard navigation of table-headers and table-cells when assistive technologies are not active. Selection affordances and slotted content within table-cells 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" |
| selectedItems | 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-rows. |
| --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-rows 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-rows. |
| --calcite-table-selection-chip-background-color | When selectionMode is "multiple" or "single" and calcite-table-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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-rows 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. | |
| calciteTableSelect | Emits when the component's selected rows change. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<this> |