@cas-smartdesign/virtual-list

A list element with ui-virtualization and infinite scrolling.

Attributes

• item-height
  • Defines the height in px of the list items.
• item-count
  • Defines the virtual number of items in the list.
• selection-type
  • Defines the mode of selection handling
  • Available values: "trigger-only", "single", "multi"
• focus-index
  • Defines the index of currently focused item
• role: string
  • Aria attribute, default value is "list"

Properties

The following properties are available:

• items any[] (default=empty)
  • Contains data for the currently rendered list items.
• itemGenerator ItemGenerator (default is the generator inside the list-item element)
  • A method that renders the list items.
• itemHeight number (default=50)
  • Reflects the corresponding attribute
• itemCount number (default=0)
  • Reflects the corresponding attribute
• selectionType string (default="trigger-only")
  • Reflects the corresponding attribute
• focusIndex number (default=undefined)
  • Reflects the corresponding attribute
• selectedIndices number[] (default=empty)
  • Contains the indices of the selected items.

Custom events

• data-request
  • Sent after scrolling the list
  • Contains the starting and ending index that is visible in the list
• 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 hasModifier property is true if mouse wheel or ctrl/meta key is down while selection. Note that the auto scroll feature is disabled while middle mouse click.

Public methods

• getListItem
  • Returns the DOM node that represents the item with the given index
  • Note that only visible items can be accessed this way
• scrollToItem
  • Scrolls the list to the item with the given index
• increaseWidthOnNextRenderIfNeeded
  • The width of the list is increased on the next rendering phase 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

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. The items are updated with the aria-setsize & aria-posinset attributes. The former one is -1 if the final size is not known to indicate infinite scrolling state.

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.
• item-index
  • The index of the item.
• last
  • Set if the item is the last in the currently rendered set of items.