Preview

Note: Card items and definition are set via JavaScript properties. See usage below.

Usage

<cs-cards></cs-cards>

<script>
  const cards = document.querySelector('cs-cards');
  cards.cardDefinition = {
    header: item => item.name,
    sections: [
      { id: 'description', header: 'Description', content: item => item.description },
      { id: 'type', header: 'Type', content: item => item.type },
    ],
  };
  cards.items = [
    { name: 'Card 1', description: 'First card description', type: 'Type A' },
    { name: 'Card 2', description: 'Second card description', type: 'Type B' },
    { name: 'Card 3', description: 'Third card description', type: 'Type A' },
  ];
</script>

Properties

aria-labelsCardsProps.AriaLabels<T>

Adds labels to the selection components (checkboxes and radio buttons) as follows:

• itemSelectionLabel ((SelectionState, Item) => string) - Determines the label for an item.
• selectionGroupLabel (string) - Specifies the label for the group selection control.
• cardsLabel (string) - Provides alternative text for the cards list. By default the contents of the header are used.

You can use the first arguments of type SelectionState to access the current selection state of the component (for example, the selectedItems list). The label function for individual items also receives the corresponding Item object. You can use the group label to add a meaningful description to the whole selection.

card-definitionCardsProps.CardDefinition<T>required

Defines what to display in each card. It has the following properties:

• header ((item) => unknown) - Responsible for displaying the card header. You receive the current item as an argument. Use fontSize="inherit" on link components inside card header.
• sections (array) - Responsible for displaying the card content. Cards can have many sections in their body. Each entry in the array is responsible for displaying a section. An entry has the following properties:
  • id: (string) - A unique identifier for the section. The property is used as a keys source for React rendering, and to match entries in the visibleSections property (if it's defined).
  • header: (unknown) - Responsible for displaying the section header.
  • content: ((item) => unknown) - Responsible for displaying the section content. You receive the current item as an argument.
  • width: (number) - Specifies the width of the card section in percent. Use this to display multiple sections in the same row. The default value is 100%.

All of the above properties are optional.

cards-per-rowReadonlyArray<CardsProps.CardsLayout>

Determines the number of cards per row for any interval of container width. It's an array whose entries are objects containing the following:

• cards (number) - Specifies the number of cards per row.
• minWidth (number) - Specifies the minimum container width (in pixels) for which this configuration object should apply.

For example, with this configuration:

[{
  cards: 1
}, {
  minWidth: 500,
  cards: 2
}, {
  minWidth: 800,
  cards: 3
}]

the cards component displays:

• 1 card per row when the container width is below 500px.
• 2 cards per row when the container width is between 500px and 799px.
• 3 cards per row when the container width is 800px or wider.

The number of cards per row can't be greater than 20.

Default value:

[{
  cards: 1
}, {
  minWidth: 768,
  cards: 2
}, {
  minWidth: 992,
  cards: 3
}, {
  minWidth: 1200,
  cards: 4
}, {
  minWidth: 1400,
  cards: 5
}, {
  minWidth: 1920,
  cards: 6
}]

entire-card-clickableboolean

Activating this property makes the entire card clickable to select it. Don't use this property if the card has any other interactive elements.

first-indexnumber

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

is-item-disabledCardsProps.IsItemDisabled<T>

Determines which items are disabled. If an item is disabled, users can't select it.

itemsReadonlyArray<T>required

Specifies the items that serve as data source for a card.

The cardDefinition property handles the display of this data.

loadingboolean default: false

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

loading-textstring default: ''

Specifies the text to display when in loading state.

render-aria-live(data: CardsProps.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.
• totalItemsCount (optional, number) - The provided totalItemsCount property.

selected-itemsReadonlyArray<T> default: this.cardDefinition.sections

Specifies the list of selected items.

selection-typeCardsProps.SelectionType default: 'none'

Specifies the selection mode. It can be either single or multi.

sticky-headerboolean

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

sticky-header-vertical-offsetnumber

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

total-items-countnumber

Use this property to inform screen readers how many cards there are. It specifies the total number of cards. If there is an unknown total number of cards, leave this property undefined.

track-byCardsProps.TrackBy<T>

Specifies the property inside items that uniquely identifies them. When it's set, it's used to provide keys for React for performance optimizations.

It's also used for connecting items and selectedItems values when they don't reference the same object.

variant'container' | 'full-page' default: 'container'

Specify a cards variant with one of the following:

• container - Use this variant to have the cards displayed as a container.
• full-page – Use this variant when cards are the entire content of a page.

visible-sectionsReadonlyArray<string>

Specifies an array containing the id of each visible section. If not set, all sections 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 of display of sections, which is controlled by the cardDefinition property.

Slots

empty

Displayed only when the list of items is empty.

filter

Use this slot to add filtering controls to the component.

header

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

pagination

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

preferences

Use this slot to add collection preferences to the component.

Events

selectionChangeCustomEvent<CardsProps.SelectionChangeDetail<T>>

Called when a user interaction causes a change in the list of selected items. The event detail contains the current list of selectedItems.