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" info="In-stock" info-state="Success">Pineapple</ui5-li>
	<ui5-li icon="nutrition-activity" description="Occurs between red and yellow" info="Expires" info-state="Warning">Orange</ui5-li>
	<ui5-li icon="nutrition-activity" description="The yellow lengthy fruit" info="Re-stock" info-state="Information">Blueberry</ui5-li>
	<ui5-li icon="nutrition-activity" description="The tropical stone fruit" info="Re-stock" info-state="Error">Mango</ui5-li>
</ui5-list>
	

List with infinite-scroll

Pineapple Orange Banana Mango Apple Peach Pomelo Pear
<ui5-list id="infiniteScrollEx" style="height: 300px" infinite-scroll>
	<ui5-li icon="nutrition-activity" description="Tropical plant with an edible fruit" info="In-stock" info-state="Success">Pineapple</ui5-li>
	<ui5-li icon="nutrition-activity" description="Occurs between red and yellow" info="Expires" info-state="Warning">Orange</ui5-li>
	<ui5-li icon="nutrition-activity" description="The yellow lengthy fruit" info="Re-stock" info-state="Error">Banana</ui5-li>
	<ui5-li icon="nutrition-activity" description="The tropical stone fruit" info="Re-stock" info-state="Error">Mango</ui5-li>
	<ui5-li icon="nutrition-activity" description="An apple is a sweet, edible fruit produced by an apple tree " info="In-stock" info-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" info="Expires" info-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" info="Re-stock" info-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." info="Re-stock" info-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 in Delete Mode

Argentina Bulgaria China
<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-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 а 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.

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
busy
boolean
false
Defines if the component would display a loading indicator at the bottom of the list. It's especially useful, when combined with infiniteScroll.
since v1.0.0-rc.6
footerText
footer-text
string
""
Defines the footer text.
headerText
header-text
string
""
Defines the ui5-list header text.

Note: If header is set this property is ignored.
infiniteScroll
infinite-scroll
boolean
false
Defines if the component would fire the load-more event when the user scrolls to the bottom of the list, and helps achieving an "infinite scroll" effect by adding new items each time.
since v1.0.0-rc.6
inset
boolean
false
Determines whether the list items are indented.
mode
ListMode
"None"
Defines the mode of the ui5-list.

Note: Available options are None, SingleSelect, SingleSelectBegin, SingleSelectEnd, MultiSelect, and Delete.
noDataText
no-data-text
string
""
Defines the text that is displayed when the ui5-list 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 ui5-list.

Note: Use ui5-li, ui5-li-custom, and ui5-li-groupheader for the intended design.
header
HTMLElement [0..n]
Defines the ui5-list 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 applicable to ui5-li-notification items only, 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 ui5-list 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 applicable to ui5-li-notification-group items only.
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 infiniteScroll 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.

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
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 buil-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.
info
string
Defines the info, displayed in the end of the list item.
since v0.13.0
infoState
info-state
ValueState
"None"
Defines the state of the info.
Available options are: "None" (by default), "Success", "Warning", "Information" and "Erorr".
since v0.13.0
type
ListItemType
"Active"
Defines the visual indication and behavior of the list items. Available options are Active (by default), Inactive and Detail.

Note: When set to Active, the item will provide visual response upon press and hover, while with type Inactive and Detail - will not.

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 ui5-li.

Note: Аlthough this slot accepts HTML Elements, it is strongly recommended that you only use text in order to preserve the intended design.

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 ui5-li-custom 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
type
ListItemType
"Active"
Defines the visual indication and behavior of the list items. Available options are Active (by default), Inactive and Detail.

Note: When set to Active, the item will provide visual response upon press and hover, while with type Inactive and Detail - will not.

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 ui5-li-custom.

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
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 ui5-li-groupheader.
Note: Аlthough this slot accepts HTML Elements, it is strongly recommended that you only use text in order to preserve the intended design.
Theme: Quartz Light Quartz Dark Quartz High Contrast Black Quartz High Contrast White Belize High Contrast Black High Contrast White
Content Density: Cozy Compact
Text Direction: LTR RTL
Apply Cancel