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 follows the SAP Fiori "Intentional Edit Pattern" (forms-editing variant)
and exposes two interaction modes:
Navigation mode (default) - Arrow keys move focus between items; [Tab] leaves the list.
Edit mode (toggled by [F2] or [F7]) - [Tab] walks through the interactive elements
inside items (buttons, links, inputs, checkboxes, etc.) and continues into the next item.
The ui5-list provides advanced keyboard handling for navigation between items.
When an item is focused the user can use the following keyboard shortcuts:
[Up] or [Down] - Navigates up and down the items
[Home] - Navigates to first item
[End] - Navigates to the last item
[Tab] or [Shift] + [Tab] - Moves focus out of the list, to the next/previous control in the tab chain
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
Edit Mode - Reaching Interactive Elements Inside Items
Interactive elements inside a list item (buttons, links, inputs, etc.) are not reached
by [Tab] from navigation mode. To activate them, the user first enters edit mode.
[F2] - While focus is on an item, moves focus to the first interactive element inside it.
While focus is on an interactive element, moves focus back to the item level.
Unlike [F7], [F2] does not remember the previous position — it always lands on the first interactive element.
[F7] - While focus is on an item, moves focus to the last remembered internal element
(or to the first interactive element if none is remembered).
While focus is on an interactive element, saves its position and moves focus back to the item level.
[Tab] or [Shift] + [Tab] - While in edit mode, moves focus through the interactive
elements within an item, then continues into the next/previous item's interactive elements,
and exits the list after the last/first element.
[Up] or [Down] - While focus is on an interactive element inside an item, moves focus
to the element at the same index in the previous/next item. Items with no interactive
elements are skipped, and boundaries of ui5-li-group are crossed.
Note: In selectionMode="Delete", the per-item delete button is reachable through
the edit-mode [Tab] flow described above, in addition to the [Delete] shortcut.
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 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.
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.
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 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 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 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
destination: object Contains information about the destination of the moved element. Has element and placement properties. source: object Contains information about the moved element under element property.
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
destination: object Contains information about the destination of the moved element. Has element and placement properties. source: object Contains information about the moved element under element property.
Fired when selection is changed by user interaction in Single, SingleStart, SingleEnd and Multiple selection modes.
Type
CustomEvent<ListSelectionChangeEventDetail>
Parameters
previouslySelectedItems: Array<ListItemBase> An array of the previously selected items. selectedItems: Array<ListItemBase> An array of the selected items.