Skip to main content

List

The ui5-list component allows displaying a list of items, advanced keyboard handling support for navigating between items, and predefined modes to improve the development efficiency.

The ui5-list is a container for the available list items:

  • ui5-li
  • ui5-li-custom
  • ui5-li-groupheader

To benefit from the built-in selection mechanism, you can use the available selection modes, such as SingleSelect, MultiSelect and Delete.

Additionally, the ui5-list provides header, footer, and customization for the list item separators.

Keyboard Handling​

Basic Navigation​

The ui5-list provides advanced keyboard handling. When a list is focused the user can use the following keyboard shortcuts in order to perform a navigation:

  • [Up] or [Down] - Navigates up and down the items
  • [Home] - Navigates to first item
  • [End] - Navigates to the last item

The user can use the following keyboard shortcuts to perform actions (such as select, delete), when the mode property is in use:

  • [Space] - Select an item (if type is 'Active') when mode is selection
  • [Delete] - Delete an item if mode property is Delete

Fast Navigation​

This component provides a build in fast navigation group which can be used via [F6] / [Shift] + [F6] / [Ctrl] + [Alt/Option] / [Down] or [Ctrl] + [Alt/Option] + [Up]. In order to use this functionality, you need to import the following module: import "@ui5/webcomponents-base/dist/features/F6Navigation.js"

ES6 Module Import​

import "@ui5/webcomponents/dist/List.js";

import "@ui5/webcomponents/dist/StandardListItem.js"; (for ui5-li)

import "@ui5/webcomponents/dist/CustomListItem.js"; (for ui5-li-custom)

import "@ui5/webcomponents/dist/GroupHeaderListItem.js"; (for ui5-li-groupheader)

Basic Sample​

Properties​

headerText​

DescriptionDefines the component header text.
Note: If header is set this property is ignored.
Typestring
Default""

footerText​

DescriptionDefines the footer text.
Typestring
Default""

indent​

DescriptionDetermines whether the component is indented.
Typeboolean
Defaultfalse

mode​

DescriptionDefines the mode of the component.
Type"None" | "SingleSelect" | "SingleSelectBegin" | "SingleSelectEnd" | "SingleSelectAuto" | "MultiSelect" | "Delete"
Default"None"

noDataText​

DescriptionDefines the text that is displayed when the component contains no items.
Typestring
Default""

separators​

DescriptionDefines the item separator style that is used.
Type"All" | "Inner" | "None"
Default"All"

growing​

DescriptionDefines whether the component will have growing capability either by pressing a More button, or via user scroll. In both cases load-more event is fired.
Restrictions: growing="Scroll" is not supported for Internet Explorer, on IE the component will fallback to growing="Button".
Type"Button" | "Scroll" | "None"
Default"None"
Since1.0.0-rc.13

growingButtonText​

DescriptionDefines the text that will be displayed inside the growing button.
Note: If not specified a built-in text will be displayed.
Note: This property takes effect if the growing property is set to the Button.
Typestring
Default""
Since1.24

busy​

DescriptionDefines if the component would display a loading indicator over the list.
Typeboolean
Defaultfalse
Since1.0.0-rc.6

busyDelay​

DescriptionDefines the delay in milliseconds, after which the busy indicator will show up for this component.
Typenumber
Default1000

accessibleName​

DescriptionDefines the accessible name of the component.
Typestring
Default""
Since1.0.0-rc.15

accessibleNameRef​

DescriptionDefines the IDs of the elements that label the input.
Typestring
Default""
Since1.0.0-rc.15

accessibleRole​

DescriptionDefines the accessible role of the component.
Typestring
Default"list"
Since1.0.0-rc.15

Slots​

default​

DescriptionDefines the items of the component.
Note: Use ui5-li, ui5-li-custom, and ui5-li-groupheader for the intended design.
TypeArray<ListItemBase>
DescriptionDefines the component header.
Note: When header is set, the headerText property is ignored.
TypeArray<HTMLElement>

Events​

item-click​

DescriptionFired when an item is activated, unless the item's type property is set to Inactive.
TypeCustomEvent<ListItemClickEventDetail>
Parametersitem: HTMLElement
The clicked item.

item-close​

DescriptionFired when the Close button of any item is clicked
Note: This event is only applicable to list items that can be closed (such as notification list items), not to be confused with item-delete.
TypeCustomEvent<ListItemCloseEventDetail>
Parametersitem: HTMLElement
the item about to be closed.
Since1.0.0-rc.8

item-toggle​

DescriptionFired when the Toggle button of any item is clicked.
Note: This event is only applicable to list items that can be toggled (such as notification group list items).
TypeCustomEvent<ListItemToggleEventDetail>
Parametersitem: HTMLElement
the toggled item.
Since1.0.0-rc.8

item-delete​

DescriptionFired when the Delete button of any item is pressed.
Note: A Delete button is displayed on each item, when the component mode property is set to Delete.
TypeCustomEvent<ListItemDeleteEventDetail>
Parametersitem: HTMLElement
the deleted item.

selection-change​

DescriptionFired when selection is changed by user interaction in SingleSelect, SingleSelectBegin, SingleSelectEnd and MultiSelect modes.
TypeCustomEvent<ListSelectionChangeEventDetail>
ParametersselectedItems: Array<ListItemBase>
An array of the selected items.
previouslySelectedItems: Array<ListItemBase>
An array of the previously selected items.

load-more​

DescriptionFired when the user scrolls to the bottom of the list.
Note: The event is fired when the growing='Scroll' property is enabled.
TypeCustomEvent
Since1.0.0-rc.6

Methods​

No methods available for this component.

CSS Parts​

No CSS parts available for this component.

More Samples​

Growing On Scroll​

The List fires an load-more event when the user scrolls to the bottom. The event can be used for loading more data (items) as shown in the sample.

Growing On Button Press​

The List fires an load-more event when the user clicks to the "Load More" button at the bottom. The event can be used for loading more data (items) as shown in the sample.

Selection Modes​

The List supports several selection modes None, SingleSelect, SingleSelectBegin, SingleSelectEnd, SingleSelectAuto, MultiSelect and Delete.

No data​

You can show a text when there aren't items (data) via the noDataText property.

Grouping​

The The GroupHeaderListItem can be used to start group section and implement grouping.

Separators​

The separators options (All, Inner, None) allows the outer lines (Inner) or all the lines (None) to be hidden.