@cas-smartdesign/list

An element that renders a given array of items in a list.

Attributes

• selection-type: string
  • Defines the type of selection that the list uses. Allowed values are:
    • single: the list items can be selected one at a time, the selected attribute is set on the selected item
    • extended: multiple list items can be selected, the selected attribute is set on the selected items
    • trigger-only: the selected attribute is not set on the selected item(s)
• role: string
  • Aria attribute, default value is "list"

Properties

• items: array
  • The data to be used by the list.
• itemGenerator: ItemGenerator
  • A function that creates a HTMLElement from an element of the items array to be rendered by the list.
  • If it is not set then the default implementation is used.
• selectedIndexes: array
  • The indexes of the currently selected items.

CSS Custom Properties

• --sd-list-base-background-color
  • Defines the background color of the list
  • This is only present due to backward compatibility reasons, as it might be easier to change the background of an item with regular css rules

Custom Events

• selection
  • Dispatched when one of the items is selected/deselected
  • Contains the index of the item and a selected flag which is when false indicates that the item is deselected
  • The originalEvent a mouse or keyboard event that triggered the selection event.

Public methods

• getListItem
  • Returns the DOM node that represents the item with the given index
• increaseWidthIfNeeded
  • The width of the list is increased to an extent, that all texts in the list-items are visible without ellipsis.
  • If the list has already reached it's maximum width, then line clamp may be enabled on the items to wrap the content if possible.
  • Note that this functionality works only if sd-list-items are rendered in the list

Selection state

The list marks the items with selected attribute in case if they are selected, but does not define any style for this state. The items generated by the itemGenerator can use this attribute if custom logic is required.

A11Y

The default role is listbox, with the corresponding option role on the items, since most of the time this element is used with a selection state. It ensures the items have an associated id which is used to update aria-activedescendant. The selection is also marked with aria-selected.

Please note that the selection type trigger-only does not provide any accessibility event in case of a selection, but it can be added externally for example with an aria-live area where the content can notify about the selection. Although normally the page would change by such a selection, so it may not be necessary to do this notification.

Attributes managed on items

In addition to above mentioned aria attributes, the items are marked with certain custom attributes:

• focused
  • Set if the item is currently focused.
• selected
  • Set if the item is selected.