List
<ui5-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-liui5-li-customui5-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
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.
Basic Navigation
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
typeis 'Active') whenselectionModeis selection - [Delete] - Delete an item if
selectionModeproperty isDelete
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] - Toggles edit mode on the focused item. Pressing [F2] again returns focus to the item level.
- [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-groupare 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.
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
accessibilityAttributes
accessibleDescription
accessibleDescriptionRef
accessibleName
accessibleNameRef
accessibleRole
footerText
growing
growingButtonText
headerText
indent
listItems
loading
loadingDelay
noDataText
selectionMode
separators
stickyHeader
Slots
default
header
Events
item-click
item-close
item-delete
item-toggle
load-more
move
move-over
selection-change
Methods
No methods available for this component.
CSS Parts
For more information on how to use CSS shadow parts, see Usage of CSS Shadow Parts.
CSS Custom States
No CSS custom states 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.
Styling Group Headers
You can customize the appearance of group headers using CSS Shadow Parts. The title part allows styling the group header text, while the header part styles the entire header container.
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.
Multiple Item Drag
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.
Wrapping Behavior
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.
Sticky Header
Use the stickyHeader property to keep the header visible during scrolling.
Accessible Role
Use the accessibleRole property on ui5-list to set the ARIA role of the list element.
Child ui5-li items automatically inherit the matching ARIA role - menuitem for Menu, option for ListBox, and treeitem for Tree - so you do not need to set it manually on every item.
Setting an explicit accessible-role attribute on an individual ui5-li takes precedence over the role inherited from the parent list.
Keyboard Handling
The ui5-list implements the SAP Fiori Intentional Edit Pattern. Interactive elements
inside a list item (such as buttons, links or inputs in a ui5-li-custom) are not reached
by Tab from outside the list — that keeps navigation between items fast.
To activate them, Tab into the list, use ↓ to focus a row, then enter edit mode:
- F2 or F7 — moves focus to the first interactive element inside the item. Press again to return focus to the item level.
- Tab / Shift+Tab — while in edit mode, walks through the interactive elements within an item, then continues into the next/previous item, and exits the list after the last/first element.
- ↑ / ↓ — while focus is on an interactive element, jumps to the element
at the same index in the previous/next item. Items with no interactive elements are skipped
and
ui5-li-groupboundaries are crossed.
Try it in the sample below — Tab into the list, use ↓ to focus a row, then press F2 or F7 to step into the row's buttons.