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.
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
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"
Defines 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".
Defines 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.
Indicates whether the List header is sticky or not. If stickyHeader is set to true, then whenever you scroll the content or the application, the header of the list will be always visible.
Defines additional accessibility attributes on different areas of the component. The accessibilityAttributes object has the following field: - growingButton: growingButton.name, growingButton.description. The accessibility attributes support the following values: - name: Defines the accessible ARIA name of the growing button. Accepts any string. - description: Defines the accessible ARIA description of the growing button. Accepts any string. Note: The accessibilityAttributes property is in an experimental state and is a subject to change.
Fired when an item is activated, unless the item's type property is set to Inactive. Note: This event is not triggered by interactions with selection components such as the checkboxes and radio buttons, associated with non-default selectionMode values, or if any other interactive component (such as a button or input) within the list item is directly clicked.
Fired 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.
Fired 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).
Fired 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.
Fired when selection is changed by user interaction in Single, SingleStart, SingleEnd and Multiple selection modes.
Type
CustomEvent<ListSelectionChangeEventDetail>
Parameters
selectedItems: Array<ListItemBase> An array of the selected items. previouslySelectedItems: Array<ListItemBase> An array of the previously selected items.
Fired 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().
Type
CustomEvent<ListMoveEventDetail>
Parameters
source: 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.
Fired 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.
Type
CustomEvent<ListMoveEventDetail>
Parameters
source: 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.
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.
You can select and drag multiple items at once when using selection-mode="Multiple". This sample demonstrates cross-list dragging and the multiple drag ghost feature.
The standard list item <ui5-li> and the list item group <ui5-li-group> supports text wrapping through the wrappingType property. When set to "Normal", long text content (title and description) will wrap to multiple lines instead of truncating with an ellipsis. For very long content, the text is displayed with a "Show More/Show Less" mechanism.
The wrapping behavior is responsive:
On mobile devices (size S), text is truncated after 100 characters
On tablets and desktop (size M and larger), text is truncated after 300 characters
This feature improves readability when displaying lengthy content in lists.
The <ui5-li-custom> is intentionally designed as a generic container to provide maximum flexibility. It can be used alongside ui5-expandable-text for long text content.