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-group

To benefit from the built-in selection mechanism, you can use the available selection modes, such as Single, Multiple 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 selectionMode property is in use:

  • [Space] - Select an item (if type is 'Active') when selectionMode is selection
  • [Delete] - Delete an item if selectionMode 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/ListItemStandard.js"; (for ui5-li)

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

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

Basic Sample​

Properties​

headerText​

DescriptionDefines the component header text.
Note: If header is set this property is ignored.
Typestring | undefined
Defaultundefined

footerText​

DescriptionDefines the footer text.
Typestring | undefined
Defaultundefined

indent​

DescriptionDetermines whether the component is indented.
Typeboolean
Defaultfalse

selectionMode​

DescriptionDefines the selection mode of the component.
Type"None" | "Single" | "SingleStart" | "SingleEnd" | "SingleAuto" | "Multiple" | "Delete"
Default"None"

noDataText​

DescriptionDefines the text that is displayed when the component contains no items.
Typestring | undefined
Defaultundefined

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 | undefined
Defaultundefined
Since1.24

loading​

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

loadingDelay​

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

accessibleName​

DescriptionDefines the accessible name of the component.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.15

accessibleNameRef​

DescriptionDefines the IDs of the elements that label the input.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.15

accessibleRole​

DescriptionDefines the accessible role of the component.
Type"List" | "Menu" | "Tree" | "ListBox"
Default"List"
Since1.0.0-rc.15

listItems​

DescriptionReturns an array containing the list item instances without the groups in a flat structure.
TypeArray<ListItemBase>
Default[]
Readonlytrue
Since2.0.0

Slots​

default​

DescriptionDefines the items of the component.
Note: Use ui5-li, ui5-li-custom, and ui5-li-group for the intended design.
TypeArray<ListItemBase | ListItemGroup>
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 selectionMode property is set to Delete.
TypeCustomEvent<ListItemDeleteEventDetail>
Parametersitem: HTMLElement
the deleted item.

selection-change​

DescriptionFired when selection is changed by user interaction in Single, SingleStart, SingleEnd and Multiple selection 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

move-over​

DescriptionFired when a movable list item is moved over a potential drop target during a dragging operation.
If the new position is valid, prevent the default action of the event using preventDefault().
TypeCustomEvent<ListMoveEventDetail>
Parameterssource: object
Contains information about the moved element under element property.
destination: object
Contains information about the destination of the moved element. Has element and placement properties.
Since2.0.0

move​

DescriptionFired when a movable list item is dropped onto a drop target.
Note: move event is fired only if there was a preceding move-over with prevented default action.
TypeCustomEvent<ListMoveEventDetail>
Parameterssource: object
Contains information about the moved element under element property.
destination: object
Contains information about the destination of the moved element. Has element and placement properties.

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, Single, SingleStart, SingleEnd, SingleAuto, Multiple and Delete.

No data​

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

Grouping​

The The ListItemGroup 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.

Drag And Drop​

The list items are draggable through the use of the movable property on ListItem.