Preview

Usage

<cs-table id="my-table">
  <cs-header slot="header" variant="h2" counter="(5)">Instances</cs-header>
</cs-table>

<script>
  const table = document.getElementById('my-table');
  table.columnDefinitions = [
    { id: 'name', header: 'Instance name', cell: item => item.name, sortingField: 'name', isRowHeader: true },
    { id: 'type', header: 'Instance type', cell: item => item.type, sortingField: 'type' },
    { id: 'state', header: 'State', cell: item => item.state },
    { id: 'launchDate', header: 'Launch date', cell: item => item.launchDate, sortingField: 'launchDate' },
  ];
  table.items = [
    { name: 'web-server-01', type: 't3.micro', state: 'Running', launchDate: '2025-01-15' },
    { name: 'api-gateway', type: 't3.small', state: 'Running', launchDate: '2025-02-20' },
    { name: 'batch-processor', type: 'c5.xlarge', state: 'Stopped', launchDate: '2024-11-03' },
    { name: 'db-replica', type: 'r5.large', state: 'Running', launchDate: '2024-08-12' },
    { name: 'dev-sandbox', type: 't3.nano', state: 'Stopped', launchDate: '2025-03-01' },
  ];
</script>

Properties

analytics-metadataTableProps.AnalyticsMetadata

Specifies additional analytics-related metadata.

• instanceIdentifier - A unique string that identifies this component instance in your application.
• flowType - Identifies the type of flow represented by the component.
• resourceType - Identifies the type of resource represented by the flow. Note: This API is currently experimental.

aria-labelsTableProps.AriaLabels<T>

Specifies alternative text for the selection components (checkboxes and radio buttons) as follows:

• selectionGroupLabel (string) - Specifies the alternative text for the whole selection and single-selection column header.
• itemSelectionLabel ((SelectionState, Item) => string) - Specifies the alternative text for item selection controls. The selection state includes:
• selectedItems (Item[]) - corresponds to table's selectedItems.
• itemsCount (optional, number) - corresponds to table's expandableRows.getItemsCount(item).
• selectedItemsCount (optional, number) - corresponds to table's expandableRows.getItemsCount(item).
• allItemsSelectionLabel ((SelectionState) => string) - Specifies the alternative text for all items selection control. The selection state includes:
• selectedItems (Item[]) - corresponds to table's selectedItems.
• itemsCount (optional, number) - corresponds to expandableRows.totalItemsCount or totalItemsCount.
• selectedItemsCount (optional, number) - corresponds to expandableRows.totalSelectedItemsCount or selectedItems.length.
• itemLoaderSelectionLabel: ((SelectionState, Item) => string) - Specifies the alternative text for resource loader selector in tables with data grouping.
• tableLabel (string) - Provides an alternative text for the table. If you use a header for this table, you may reuse the string to provide a caption-like description. For example, tableLabel=Instances will be announced as 'Instances table'.
• resizerRoleDescription (string) - Provides role description for table column resizer buttons.
• resizerTooltipText (string) - Provides text for the table column resizer tooltip.
• activateEditLabel (EditableColumnDefinition, Item) => string - Specifies an alternative text for the edit button in editable cells.
• cancelEditLabel (EditableColumnDefinition) => string - Specifies an alternative text for the cancel button in editable cells.
• submitEditLabel (EditableColumnDefinition) => string - Specifies an alternative text for the submit button in editable cells.
• successfulEditLabel (EditableColumnDefinition) => string - Specifies an alternative text for the success icon in editable cells. This text is also announced to screen readers.
• submittingEditText (EditableColumnDefinition) => string - Specifies a text that is announced to screen readers when a cell edit operation is submitted.
• expandButtonLabel (Item) => string - Specifies an alternative text for row expand button.
• collapseButtonLabel (Item) => string - Specifies an alternative text for row collapse button.

cell-vertical-align'middle' | 'top'

Determines the alignment of the content inside table cells. This property affects all cells, including the ones in the selection column. To target individual cells use columnDefinitions.verticalAlign, that takes precedence over cellVerticalAlign.

column-definitionsReadonlyArray<TableProps.ColumnDefinition<T>>required

The columns configuration object

• id (string) - Specifies a unique column identifier. The property is used 1) as a keys source for React rendering, and 2) to match entries in the columnDisplay property, if defined.
• header (unknown) - Determines the display of the column header.
• cell ((item) => unknown) - Determines the display of a cell's content. You receive the current table row item as an argument.
• width (string | number) - Specifies the column width. Corresponds to the width css-property. If the width is not set, the browser automatically adjusts the column width based on the content. When resizableColumns property is set to true, additional constraints apply: 1) string values are not allowed, and 2) the last visible column always fills the remaining space of the table so the specified width is ignored.
• minWidth (string | number) - Specifies the minimum column width. Corresponds to the min-width css-property. When resizableColumns property is set to true, additional constraints apply: 1) string values are not allowed, and 2) the column can't resize below than the specified width (defaults to "120px"). We recommend that you set a minimum width of at least 176px for columns that are editable.
• maxWidth (string | number) - Specifies the maximum column width. Corresponds to the max-width css-property. Note that when the resizableColumns property is set to true this property is ignored.
• ariaLabel (LabelData => string) - An optional function that's called to provide an aria-label for the cell header. It receives the current sorting state of this column, the direction it's sorted in, and an indication of whether the sorting is disabled, as three Boolean values: sorted, descending and disabled. We recommend that you use this for sortable columns to provide more meaningful labels based on the current sorting direction.
• sortingField (string) - Enables default column sorting. The value is used in collection hooks to reorder the items. Provide the name of the property within each item that should be used for sorting by this column. For more complex sorting use sortingComparator instead.
• sortingComparator ((T, T) => number) - Enables custom column sorting. The value is used in collection hooks to reorder the items. This property accepts a custom comparator that is used to compare two items. The comparator must implement ascending ordering, and the output is inverted automatically in case of descending order. If present, the sortingField property is ignored.
• counter ((ItemCounterData) => string) - Specifies secondary cell content, displayed next to the primary. Use it to display resource counters in the first column of expandable tables with data grouping.
• editConfig (EditConfig) - Enables inline editing in column when present. The value is used to configure the editing behavior.
  • editConfig.ariaLabel (string) - Specifies a label for the edit control. Visually hidden but read by screen readers.
  • editConfig.errorIconAriaLabel (string) - Specifies an ariaLabel for the error icon that is displayed when the validation fails.
  • editConfig.editIconAriaLabel (string) - Specifies an alternate text for the edit icon used in column header.
  • editConfig.constraintText (string) - Constraint text that is displayed below the edit control.
  • editConfig.disabledReason ((item) => string | undefined) - A function that determines whether inline edit for certain items is disabled, and provides a reason why. Return a string from the function to disable inline edit with a reason. Return undefined (or no return) from the function allow inline edit.
  • editConfig.validation ((item, value) => string) - A function that allows you to validate the value of the edit control. Return a string from the function to display an error message. Return undefined (or no return) from the function to indicate that the value is valid.
  • editConfig.editingCell ((item, cellContext) => unknown) - Determines the display of a cell's content when inline editing is active on a cell; You receive the current table row item and a cellContext object as arguments. The cellContext object contains the following properties:
    • cellContext.currentValue - State to keep track of a value in input fields while editing.
    • cellContext.setValue - Function to update currentValue. This should be called when the value in input field changes.
    • cellContext.submitValue - Function to submit the currentValue.
  • editConfig.disableNativeForm (boolean) - Disables the use of a <form> element to capture submissions inside the inline editor. If enabled, ensure that any text inputs in the editing cell submit the cell value when the Enter key is pressed, using cellContext.submitValue.
• isRowHeader (boolean) - Specifies that cells in this column should be used as row headers.
• hasDynamicContent (boolean) - Specifies that cells in this column may have dynamic content. The contents will then be observed to update calculated column widths. This may have a negative performance impact, so should be used only if necessary. It has no effect if resizableColumns is set to true.
• verticalAlign ('middle' | 'top') - Determines the alignment of the content in the table cell.

column-displayReadonlyArray<ColumnDisplayProperties>

Specifies an array that represents the table columns in the order in which they will be displayed, together with their visibility.

If not set, all columns are displayed and the order is dictated by the columnDefinitions property.

Use it in conjunction with the content display preference of the collection preferences component.

content-density'comfortable' | 'compact' default: 'comfortable'

Toggles the content density of the table. Defaults to 'comfortable'.

enable-keyboard-navigationboolean

Use this property to activate advanced keyboard navigation and focusing behaviors. When set to true, table cells become navigable with arrow keys, and the entire table has a single tab stop.

By default, the keyboard navigation is active for tables with expandable rows.

expandable-rowsTableProps.ExpandableRows<T>

Use this property to define expandable table rows. The expandableRows configuration object consists of:

• getItemChildren ((Item) => Item[]) - Use it to define nested data that are shown when an item gets expanded.
• isItemExpandable ((Item) => boolean) - Use it for items that can be expanded to show nested data.
• expandedItems (Item[]) - Use it to represent the expanded state of items.
• onExpandableItemToggle (TableProps.OnExpandableItemToggle) - Called when an item's expand toggle is clicked.
• groupSelection (optional, GroupSelectionState) - Tree-like selection state for tables with grouped data. When defined, the properties selectionType and selectedItems no longer apply. It reads as (assuming item "a.1" is nested under "a"):
• { inverted: false, toggledItems: [] } - no items are selected;
• { inverted: true, toggledItems: [] } - all items are selected;
• { inverted: false, toggledItems: ["a", "a.1"] } - all items nested under "a", unless also nested under "a.1", are selected.
• { inverted: true, toggledItems: ["a", "a.1"] } - the opposite of above.
• onGroupSelectionChange (optional, TableProps.OnGroupSelectionChange) - Called when group selection changes.
• getItemsCount (optional, (Item) => number) - Use it to indicate the number of resources nested under the given item. The value is passed as itemsCount property to the columnDefinitions[index].counter and ariaLabels.itemSelectionLabel functions.
• totalItemsCount (optional, number) - Use it to indicate the total number of resources in the table. The value is passed as itemsCount property to the ariaLabels.allItemsSelectionLabel.
• getSelectedItemsCount (optional, (Item) => number) - Use it to indicate the number of selected resources nested under the given item. The value is passed as selectedItemsCount property to the columnDefinitions[index].counter and ariaLabels.itemSelectionLabel functions.
• totalSelectedItemsCount (optional, number) - Use it to indicate the total number of selected resources in the table. The value is passed as selectedItemsCount property to the ariaLabels.allItemsSelectionLabel.

first-indexnumber

Use this property to inform screen readers which range of items is currently displayed in the table. It specifies the index (1-based) of the first item in the table.

get-loading-statusTableProps.GetLoadingStatus<T>

A function that specifies the current status of loading more items. It is called once for the entire table with item=null and then for each expanded item. The function result is one of the four possible states:

• pending - Indicates that no request in progress, but more options may be loaded.
• loading - Indicates that data fetching is in progress.
• finished - Indicates that loading has finished and no more requests are expected.
• error - Indicates that an error occurred during fetch.

is-item-disabledTableProps.IsItemDisabled<T>

Determines whether a given item is disabled. If an item is disabled, the user can't select it.

itemsReadonlyArray<T>required

Specifies the data that's displayed in the table rows. Each item contains the data for one row. The display of a row is handled by the cell property of each column definition in the columnDefinitions property.

loadingboolean default: false

Renders the table in a loading state. We recommend that you also set a loadingText.

loading-textstring default: ''

Specifies the text that's displayed when the table is in a loading state.

render-aria-live(data: TableProps.LiveAnnouncement) => string

Use this function to announce page changes to screen reader users. The function argument takes the following properties:

• firstIndex (number) - The provided firstIndex property which defaults to 1 when not defined.
• lastIndex (number) - The index of the last visible item of the table.
• visibleItemsCount (number) - The number of rendered table items.
• totalItemsCount (optional, number) - The provided totalItemsCount property. Important: in tables with expandable rows the firstIndex, lastIndex, and totalItemsCount reflect the top-level items only.

render-loader-counter(detail: TableProps.RenderLoaderCounterDetail<T>) => unknown

Renders loader counter that is appended to the loader content in all loader states.

render-loader-empty(detail: TableProps.RenderLoaderEmptyDetail<T>) => unknown

Renders loader row content for empty row state: the loading status is "finished", and the row is expanded but has empty children array.

The empty loader state is only supported for expandable rows. Use empty slot if the table items array is empty.

render-loader-error(detail: TableProps.RenderLoaderDetail<T>) => unknown

Renders loader row content for error state.

render-loader-loading(detail: TableProps.RenderLoaderDetail<T>) => unknown

Renders loader row content for loading state.

render-loader-pending(detail: TableProps.RenderLoaderDetail<T>) => unknown

Renders loader row content for pending state.

resizable-columnsboolean

Specifies if columns can be resized. If set to true, users can resize the columns in the table.

selected-itemsReadonlyArray<T> default: []

List of selected items.

selection-typeTableProps.SelectionType

Specifies the selection type ('single' | 'multi').

sorting-columnTableProps.SortingColumn<T> default: this.selectedItems ? [...this.selectedItems] : []

Specifies the definition object of the currently sorted column. Make sure you pass an object that's present in the columnDefinitions array.

sorting-descendingboolean default: false

Specifies whether to use a descending sort order.

sorting-disabledboolean default: false

Specifies if sorting buttons are disabled. For example, use this property to prevent the user from sorting before items are fully loaded.

sticky-columnsTableProps.StickyColumns

Specifies the number of first and/or last columns that should be sticky.

If the available scrollable space is less than a certain threshold, the feature is deactivated.

Use it in conjunction with the sticky columns preference of the collection preferences component.

sticky-headerboolean default: false

If set to true, the table header remains visible when the user scrolls down.

Do not use stickyHeader conditionally. Instead, keep its value constant during the component lifecycle.

sticky-header-vertical-offsetnumber

Specifies a vertical offset (in pixels) for the sticky header. For example, use this if you need to position the sticky header below other fixed position elements on the page.

striped-rowsboolean default: false

Specifies if table rows alternate being shaded and unshaded. If set to true, every other row will be shaded.

submit-editTableProps.SubmitEditFunction<T>

Specifies a function that will be called after user submits an inline edit. Return a promise to keep loading state while the submit request is in progress.

total-items-countnumber

Use this property to inform screen readers how many items there are in a table. It specifies the total count of all items in a table. If there is an unknown total of items in a table, leave this property undefined.

track-byTableProps.TrackBy<T>

Specifies a property that uniquely identifies an individual item. When it's set, it's used to provide keys for React for performance optimizations.

It is also used in the following situations:

• to connect items and selectedItems values when they reference different objects.
• to connect items and expandableRows.expandedItems values when they reference different objects.
• to attach successful edit state to the correct item if its row index changes after editing.

variantTableProps.Variant default: 'container'

Specify a table variant with one of the following:

• container - Use this variant to have the table displayed within a container.
• borderless - Use this variant when the table should have no outer borders or shadow (such as in a dashboard item container).
• embedded - Use this variant within a parent container (such as a modal, expandable section, container or split panel). Deprecated, replaced by borderless and container.
• stacked - Use this variant adjacent to other stacked containers (such as a container, table).
• full-page – Use this variant when the table is the entire content of a page.

visible-columnsReadonlyArray<string>

Specifies an array containing the ids of visible columns. If not set, all columns are displayed.

Use it in conjunction with the visible content preference of the collection preferences component.

The order of ids doesn't influence the order in which columns are displayed - this is dictated by the columnDefinitions property.

wrap-linesboolean default: false

Specifies if text wraps within table cells. If set to true, long text within cells may wrap onto multiple lines instead of being truncated with an ellipsis.

Slots

empty

Displayed when the items property is an empty array. Use it to render an empty or no-match state.

filter

Use this slot to add filtering controls to the table.

footer

Footer of the table container.

header

Heading element of the table container. Use the header component.

pagination

Use this slot to add the pagination component to the table.

preferences

Use this slot to add collection preferences to the table.

Events

columnWidthsChangeCustomEvent<TableProps.ColumnWidthsChangeDetail>

Fired when the user resizes a table column. The event detail contains an array of column widths in pixels, including the hidden via preferences columns. Use this event to persist the column widths.

editCancelCustomEvent<void>

Called whenever user cancels an inline edit. Use this function to reset any validation states, or show warning for unsaved changes.

rowClickCustomEvent<TableProps.OnRowClickDetail<T>>

Note: This feature is provided for backwards compatibility. Its use is not recommended, and it may be deprecated in the future.

Called when the user clicked at a table row. The event detail contains the index of the clicked row and the row object itself. Use this event to define a row click behavior.

rowContextMenuCustomEvent<TableProps.OnRowContextMenuDetail<T>>

Note: This feature is provided for backwards compatibility. Its use is not recommended, and it may be deprecated in the future.

Called when the user clicked at a table row with the right mouse click. The event detail contains the index of the clicked row and the row object itself. Use this event to override the default browser context menu behavior.

selectionChangeCustomEvent<TableProps.SelectionChangeDetail<T>>

Fired when a user interaction triggers a change in the list of selected items. The event detail contains the new state for selectedItems.

sortingChangeCustomEvent<TableProps.SortingState<T>>

Called when either the column to sort by or the direction of sorting changes upon user interaction. The event detail contains the current sortingColumn and isDescending.