UI5 Web Components
Search

List

@ui5/webcomponents
<ui5-list>

Basic List

Pineapple Orange Blueberry Mango 
<ui5-list id="myList" class="full-width">
	<ui5-li icon="nutrition-activity" description="Tropical plant with an edible fruit" additional-text="In-stock" additional-text-state="Success">Pineapple</ui5-li>
	<ui5-li icon="nutrition-activity" description="Occurs between red and yellow" additional-text="Expires" additional-text-state="Warning">Orange</ui5-li>
	<ui5-li icon="nutrition-activity" description="The yellow lengthy fruit" additional-text="Re-stock" additional-text-state="Information">Blueberry</ui5-li>
	<ui5-li icon="nutrition-activity" description="The tropical stone fruit" additional-text="Re-stock" additional-text-state="Error">Mango</ui5-li>
</ui5-list>

List with growing="Scroll"

Pineapple Orange Banana Mango Apple Peach Pomelo Pear 
<ui5-list id="infiniteScrollEx" style="height: 300px" growing="Scroll">
	<ui5-li icon="nutrition-activity" description="Tropical plant with an edible fruit" additional-text="In-stock" additional-text-state="Success">Pineapple</ui5-li>
	<ui5-li icon="nutrition-activity" description="Occurs between red and yellow" additional-text="Expires" additional-text-state="Warning">Orange</ui5-li>
	<ui5-li icon="nutrition-activity" description="The yellow lengthy fruit" additional-text="Re-stock" additional-text-state="Error">Banana</ui5-li>
	<ui5-li icon="nutrition-activity" description="The tropical stone fruit" additional-text="Re-stock" additional-text-state="Error">Mango</ui5-li>
	<ui5-li icon="nutrition-activity" description="An apple is a sweet, edible fruit produced by an apple tree " additional-text="In-stock" additional-text-state="Success">Apple</ui5-li>
	<ui5-li icon="nutrition-activity" description="The peach (Prunus persica) is a deciduous tree native to the region of Northwest China" additional-text="Expires" additional-text-state="Warning">Peach</ui5-li>
	<ui5-li icon="nutrition-activity" description="The pomelo is the largest citrus fruit from the family Rutaceae and the principal ancestor of the grapefruit" additional-text="Re-stock" additional-text-state="Error">Pomelo</ui5-li>
	<ui5-li icon="nutrition-activity" description="The pear (/ˈpɛər/) tree and shrub are a species of genus Pyrus, bearing the pomaceous fruit of the same name." additional-text="Re-stock" additional-text-state="Error">Pear</ui5-li>
</ui5-list>

<script>
	const infiniteScrollEx = document.getElementById("infiniteScrollEx");

	infiniteScrollEx.addEventListener("load-more", (e) => {
		infiniteScrollEx.busy = true;

		setTimeout(() => {
			for(let i = 0; i < 5; i++) {
				const li = document.createElement("ui5-li");
				li.textContent = "Fruit name" + i;
				infiniteScrollEx.appendChild(li);
			}

			infiniteScrollEx.busy = false;
		}, 200);
	});
</script>

List in Single-selection Mode

Argentina Bulgaria China Denmark (ui5-li type='Inactive') 
<ui5-list id="country-selector" mode="SingleSelect" header-text="Select a country:">
	<ui5-li selected icon="map" icon-end>Argentina</ui5-li>
	<ui5-li icon="map" icon-end>Bulgaria</ui5-li>
	<ui5-li icon="map" icon-end>China</ui5-li>
	<ui5-li type="Inactive" icon="map" icon-end>Denmark (ui5-li type='Inactive')</ui5-li>
</ui5-list>

<script>
	document.getElementById('country-selector').addEventListener("selection-change", function (event) {
		var selectedItems = event.detail.selectedItems;

		alert("The selected item:  " + selectedItems[0].textContent);
	});
</script>

List in Multi-selection Mode

Pineapple Orange Banana Mango 
<ui5-list id="myList1" mode='MultiSelect' header-text="Multiple selection is possible">
	<ui5-li>Pineapple</ui5-li>
	<ui5-li selected>Orange</ui5-li>
	<ui5-li>Banana</ui5-li>
	<ui5-li>Mango</ui5-li>
</ui5-list>

Busy List

<ui5-list header-text="Fetching data ..." busy></ui5-list>

List With GroupHeaders

Front End Developers Jennifer Lora Carlotta Back End Developers Clark Ellen Adam FullStack Developers Susan David Natalie 
<ui5-list header-text="Team Members" mode="MultiSelect">
	<ui5-li-groupheader>Front End Developers</ui5-li-groupheader>
	<ui5-li image="../../../assets/images/avatars/woman_avatar_3.png" icon="navigation-right-arrow" icon-end>Jennifer</ui5-li>
	<ui5-li image="../../../assets/images/avatars/woman_avatar_4.png" icon="navigation-right-arrow" icon-end>Lora</ui5-li>
	<ui5-li image="../../../assets/images/avatars/woman_avatar_5.png" icon="navigation-right-arrow" icon-end>Carlotta</ui5-li>

	<ui5-li-groupheader>Back End Developers</ui5-li-groupheader>
	<ui5-li image="../../../assets/images/avatars/man_avatar_1.png"  icon="navigation-right-arrow" icon-end>Clark</ui5-li>
	<ui5-li image="../../../assets/images/avatars/woman_avatar_1.png" icon="navigation-right-arrow" icon-end>Ellen</ui5-li>
	<ui5-li image="../../../assets/images/avatars/man_avatar_2.png" icon="navigation-right-arrow" icon-end>Adam</ui5-li>

	<ui5-li-groupheader>FullStack Developers</ui5-li-groupheader>
	<ui5-li image="../../../assets/images/avatars/woman_avatar_2.png" icon="navigation-right-arrow" icon-end>Susan</ui5-li>
	<ui5-li image="../../../assets/images/avatars/man_avatar_3.png" icon="navigation-right-arrow" icon-end>David</ui5-li>
	<ui5-li image="../../../assets/images/avatars/woman_avatar_3.png" icon="navigation-right-arrow" icon-end>Natalie</ui5-li>
</ui5-list>

List items using imageContent slot

Avatar inside imageContent slot
Avatar inside imageContent slot
Woman image 
<ui5-list class="full-width">
	<ui5-li> Avatar inside imageContent slot
		<div slot="imageContent">
			<ui5-avatar shape="Square" initials="ABC" color-scheme="Accent2"></ui5-avatar>
		</div>
	</ui5-li>
	<ui5-li> Avatar inside imageContent slot
		<div slot="imageContent">
			<ui5-avatar >
				<img src="./img/woman_avatar_5.png" alt="Woman image">
			</ui5-avatar>
		</div>
	</ui5-li>
</ui5-list>

List in Delete Mode

Argentina Bulgaria China Denmark
Custom Delete Button 
<ui5-list id="myList5" mode="Delete" header-text="Note: The list items removal is up to application developers">
	<ui5-li>Argentina</ui5-li>
	<ui5-li>Bulgaria</ui5-li>
	<ui5-li>China</ui5-li>
	<ui5-li>Denmark
		<div slot="deleteButton">
			<ui5-button>Custom Delete Button</ui5-button>
		</div>
	</ui5-li>
</ui5-list>

List with No Data

<ui5-list class="full-width" header-text="Products" no-data-text="No Data Available" separators="None"></ui5-list>

List Item Separation Types

Item #1 Item #2 Item #3 Devilered Pending Declined 
<ui5-list header-text="No separators" separators="None" class="full-width">
	<ui5-li icon="product">Item #1</ui5-li>
	<ui5-li icon="product">Item #2</ui5-li>
	<ui5-li icon="product">Item #3</ui5-li>
</ui5-list>
<ui5-list header-text="Inner separators" separators="Inner" class="full-width">
	<ui5-li icon="shipping-status">Devilered</ui5-li>
	<ui5-li icon="shipping-status">Pending</ui5-li>
	<ui5-li icon="shipping-status">Declined</ui5-li>
</ui5-list>

Overview

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/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 or Ctrl + Alt(Option) + Down / 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)

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
accessibleName
accessible-name
string
""
Defines the accessible name of the component.
since v1.0.0-rc.15
accessibleNameRef
accessible-name-ref
string
""
Defines the IDs of the elements that label the input.
since v1.0.0-rc.15
accessibleRole
accessible-role
string
"list"
Defines the accessible role of the component.

since v1.0.0-rc.15
busy
boolean
false
Defines if the component would display a loading indicator over the list.
since v1.0.0-rc.6
busyDelay
busy-delay
Integer
1000
Defines the delay in milliseconds, after which the busy indicator will show up for this component.
footerText
footer-text
string
""
Defines the footer text.
growing
ListGrowingMode
"None"
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.

Available options:

Button - Shows a More button at the bottom of the list, pressing of which triggers the load-more event.
Scroll - The load-more event is triggered when the user scrolls to the bottom of the list;
None (default) - The growing is off.

Restrictions: growing="Scroll" is not supported for Internet Explorer, on IE the component will fallback to growing="Button".
since v1.0.0-rc.13
headerText
header-text
string
""
Defines the component header text.

Note: If header is set this property is ignored.
indent
boolean
false
Determines whether the component is indented.
mode
ListMode
"None"
Defines the mode of the component.

Note: Available options are None, SingleSelect, SingleSelectBegin, SingleSelectEnd, MultiSelect, and Delete.
noDataText
no-data-text
string
""
Defines the text that is displayed when the component contains no items.
separators
ListSeparators
"All"
Defines the item separator style that is used.

Notes:
  • Avalaible options are All, Inner, and None.
  • When set to None, none of the items are separated by horizontal lines.
  • When set to Inner, the first item doesn't have a top separator and the last item doesn't have a bottom separator.

Slots

This Element provides slot(s). This means it can display its child nodes.
Unless targeting the default slot, use the slot attribute to define the destination slot for each child.
Text, along with HTML Elements with no slot attribute, goes the the default slot.

Slot
Type
Description
default
HTMLElement [0..n]
Defines the items of the component.

Note: Use ui5-li, ui5-li-custom, and ui5-li-groupheader for the intended design.
header
HTMLElement [0..n]
Defines the component header.

Note: When header is set, the headerText property is ignored.

Events

This Web Component fires semantic events upon user interaction. You can bind to these events with the standard DOM APIs, such as addEventListener.

Name
Description
item-click
Fired when an item is activated, unless the item's type property is set to Inactive.
item
type: HTMLElement
description: The clicked item.
item-close
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.
since v1.0.0-rc.8
item
type: HTMLElement
description: the item about to be closed.
item-delete
Fired 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.
item
type: HTMLElement
description: the deleted item.
item-toggle
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).
since v1.0.0-rc.8
item
type: HTMLElement
description: the toggled item.
load-more
Fired when the user scrolls to the bottom of the list.

Note: The event is fired when the growing='Scroll' property is enabled.
since v1.0.0-rc.6
selection-change
Fired when selection is changed by user interaction in SingleSelect, SingleSelectBegin, SingleSelectEnd and MultiSelect modes.
selectedItems
type: Array
description: An array of the selected items.
previouslySelectedItems
type: Array
description: An array of the previously selected items.

StandardListItem

The ui5-li represents the simplest type of item for a ui5-list. This is a list item, providing the most common use cases such as text, image and icon.

CSS Shadow Parts

CSS Shadow Parts allow developers to style elements inside the Shadow DOM.
The ui5-li exposes the following CSS Shadow Parts:
  • title - Used to style the title of the list item
  • description - Used to style the description of the list item
  • additional-text - Used to style the additionalText of the list item
  • icon - Used to style the icon of the list item

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
accessibleName
accessible-name
string
""
Defines the text alternative of the component. Note: If not provided a default text alternative will be set, if present.
since v1.0.0-rc.15
additionalText
additional-text
string
Defines the additionalText, displayed in the end of the list item.
since v1.0.0-rc.15
additionalTextState
additional-text-state
sap.ui.webc.base.types.ValueState
"None"
Defines the state of the additionalText.
Available options are: "None" (by default), "Success", "Warning", "Information" and "Error".
since v1.0.0-rc.15
description
string
Defines the description displayed right under the item text, if such is present.
since v0.8.0
icon
string
Defines the icon source URI.

Note: SAP-icons font provides numerous built-in icons. To find all the available icons, see the Icon Explorer.
iconEnd
icon-end
boolean
false
Defines whether the icon should be displayed in the beginning of the list item or in the end.

Note: If image is set, the icon would be displayed after the image.
image
string
Defines the image source URI.

Note: The image would be displayed in the beginning of the list item.
navigated
boolean
The navigated state of the list item. If set to true, a navigation indicator is displayed at the end of the list item.
since v1.10.0
type
sap.ui.webc.main.types.ListItemType
"Active"
Defines the visual indication and behavior of the list items. Available options are Active (by default), Inactive, Detail and Navigation.

Note: When set to Active or Navigation, the item will provide visual response upon press and hover, while with type Inactive and Detail - will not.
selected
boolean
false
Defines the selected state of the ListItem.

Slots

This Element provides slot(s). This means it can display its child nodes.
Unless targeting the default slot, use the slot attribute to define the destination slot for each child.
Text, along with HTML Elements with no slot attribute, goes the the default slot.

Slot
Type
Description
default
Node [0..n]
Defines the text of the component.

Note: Although this slot accepts HTML Elements, it is strongly recommended that you only use text in order to preserve the intended design.
imageContent
HTMLElement [0..n]
Note: While the slot allows option for setting custom avatar, to match the design guidelines, please use the ui5-avatar with it`s default size - S. Note: If bigger ui5-avatar needs to be used, then the size of the ui5-li should be customized in order to fit.
deleteButton
sap.ui.webc.main.IButton
Defines the delete button, displayed in "Delete" mode. Note: While the slot allows custom buttons, to match design guidelines, please use the ui5-button component. Note: When the slot is not present, a built-in delete button will be displayed.

Events

This Web Component fires semantic events upon user interaction. You can bind to these events with the standard DOM APIs, such as addEventListener.

Name
Description
detail-click
Fired when the user clicks on the detail button when type is Detail.

CustomListItem

A component to be used as custom list item within the ui5-list the same way as the standard ui5-li. The component accepts arbitrary HTML content to allow full customization.

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
accessibleName
accessible-name
string
""
Defines the text alternative of the component. Note: If not provided a default text alternative will be set, if present.
since v1.0.0-rc.15
navigated
boolean
The navigated state of the list item. If set to true, a navigation indicator is displayed at the end of the list item.
since v1.10.0
type
sap.ui.webc.main.types.ListItemType
"Active"
Defines the visual indication and behavior of the list items. Available options are Active (by default), Inactive, Detail and Navigation.

Note: When set to Active or Navigation, the item will provide visual response upon press and hover, while with type Inactive and Detail - will not.
selected
boolean
false
Defines the selected state of the ListItem.

Slots

This Element provides slot(s). This means it can display its child nodes.
Unless targeting the default slot, use the slot attribute to define the destination slot for each child.
Text, along with HTML Elements with no slot attribute, goes the the default slot.

Slot
Type
Description
default
Node [0..n]
Defines the content of the component.
deleteButton
sap.ui.webc.main.IButton
Defines the delete button, displayed in "Delete" mode. Note: While the slot allows custom buttons, to match design guidelines, please use the ui5-button component. Note: When the slot is not present, a built-in delete button will be displayed.

Events

This Web Component fires semantic events upon user interaction. You can bind to these events with the standard DOM APIs, such as addEventListener.

Name
Description
detail-click
Fired when the user clicks on the detail button when type is Detail.

GroupHeaderListItem

The ui5-li-groupheader is a special list item, used only to separate other list items into logical groups.

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
accessibleName
accessible-name
string
""
Defines the text alternative of the component. Note: If not provided a default text alternative will be set, if present.
since v1.0.0-rc.15
selected
boolean
false
Defines the selected state of the ListItem.

Slots

This Element provides slot(s). This means it can display its child nodes.
Unless targeting the default slot, use the slot attribute to define the destination slot for each child.
Text, along with HTML Elements with no slot attribute, goes the the default slot.

Slot
Type
Description
default
Node [0..n]
Defines the text of the component.
Note: Although this slot accepts HTML Elements, it is strongly recommended that you only use text in order to preserve the intended design.
Theme: Morning Horizon (Light) Evening Horizon (Dark) Horizon High Contrast Black Horizon High Contrast White Quartz Light Quartz Dark Quartz High Contrast Black Quartz High Contrast White
Content Density: Cozy Compact
Text Direction: LTR RTL
Apply Cancel