UI5 Web Components
Search

Tree

v1.0.0-rc.8
@ui5/webcomponents
<ui5-tree>

Basic Tree

<ui5-tree id="myTree" class="full-width">
	<ui5-tree-item expanded text="Tree 1" icon="paste" selected>
		<ui5-tree-item expanded text="Tree 1.1" selected>
			<ui5-tree-item text="Tree 1.1.1"></ui5-tree-item>
			<ui5-tree-item text="Tree 1.1.2"></ui5-tree-item>
		</ui5-tree-item>
	</ui5-tree-item>
	<ui5-tree-item text="Tree 2" icon="copy">
		<ui5-tree-item text="Tree 2.1">
			<ui5-tree-item text="Tree 2.1.1"></ui5-tree-item>
			<ui5-tree-item text="Tree 2.1.2">
				<ui5-tree-item text="Tree 2.1.2.1"></ui5-tree-item>
				<ui5-tree-item text="Tree 2.1.2.2"></ui5-tree-item>
				<ui5-tree-item text="Tree 2.1.2.3"></ui5-tree-item>
				<ui5-tree-item text="Tree 2.1.2.5"></ui5-tree-item>
			</ui5-tree-item>
		</ui5-tree-item>
		<ui5-tree-item text="Tree 2.2"></ui5-tree-item>
	</ui5-tree-item>

	<ui5-tree-item expanded text="Tree 3 (no icon)">
	</ui5-tree-item>
</ui5-tree>

Tree with multiple selection

<ui5-tree id="myTree" class="full-width">
	<ui5-tree-item expanded text="Tree 1" icon="paste" selected>
		<ui5-tree-item expanded text="Tree 1.1" selected>
			<ui5-tree-item text="Tree 1.1.1"></ui5-tree-item>
			<ui5-tree-item text="Tree 1.1.2"></ui5-tree-item>
		</ui5-tree-item>
	</ui5-tree-item>
	<ui5-tree-item text="Tree 2" icon="copy">
		<ui5-tree-item text="Tree 2.1">
			<ui5-tree-item text="Tree 2.1.1"></ui5-tree-item>
			<ui5-tree-item text="Tree 2.1.2">
				<ui5-tree-item text="Tree 2.1.2.1"></ui5-tree-item>
				<ui5-tree-item text="Tree 2.1.2.2"></ui5-tree-item>
				<ui5-tree-item text="Tree 2.1.2.3"></ui5-tree-item>
				<ui5-tree-item text="Tree 2.1.2.5"></ui5-tree-item>
			</ui5-tree-item>
		</ui5-tree-item>
		<ui5-tree-item text="Tree 2.2"></ui5-tree-item>
	</ui5-tree-item>

	<ui5-tree-item expanded text="Tree 3 (no icon)">
	</ui5-tree-item>
</ui5-tree>

Tree with dynamic content

<ui5-busy-indicator id="busy" class="full-width">
	<ui5-tree id="treeDynamic" mode="None" class="full-width">
		<ui5-tree-item text="Has pre-loaded children">
			<ui5-tree-item text="Child 1"></ui5-tree-item>
			<ui5-tree-item text="Child 2"></ui5-tree-item>
		</ui5-tree-item>

		<ui5-tree-item text="Has no children at all"></ui5-tree-item>

		<ui5-tree-item id="dynamicNode" text="Has children, but not yet loaded" has-children></ui5-tree-item>
	</ui5-tree>
</ui5-busy-indicator>

<script>
	var busyIndicator = document.getElementById("busy");
	var dynamicTree = document.getElementById("treeDynamic");
	dynamicTree.addEventListener("item-toggle", function(event) {
		var item = event.detail.item; // get the node that is toggled

		// Only for the dynamic node, and only when it's empty
		if (item.id === "dynamicNode" && item.children.length === 0) {
			busyIndicator.active = true; // block the tree from the user
			event.preventDefault(); // do not let the toggle button switch yet
			setTimeout(function() {
				var newItem = document.createElement("ui5-tree-item"); // Fetching from db....
				newItem.text = "Node fetched from DB after 2 sec";
				item.appendChild(newItem); // add the newly fetched node to the tree
				item.toggle(); // now manually switch the toggle button
				busyIndicator.active = false; // unblock the tree
			}, 2000);
		}
	});
</script>

Tree with custom items

Tree with custom items
Level 1 Level 2 Option 2.1 Option 2.3 Level 3 
<ui5-tree mode="MultiSelect">
	<div slot="header" class="hdr">
		<ui5-title>Tree with custom items</ui5-title>
	</div>
	<ui5-tree-item-custom
		expanded="true"
		show-toggle-button
		hide-selection-element
		type="Active"
		level="1"
	>
		<ui5-button slot="content">Level 1</ui5-button>

		<ui5-tree-item-custom
			type="Active"
			show-toggle-button
			level="2"
			expanded="true"
		>
			<ui5-select slot="content">
				<ui5-option>Level 2</ui5-option>
				<ui5-option>Option 2.1</ui5-option>
				<ui5-option>Option 2.3</ui5-option>
			</ui5-select>

			<ui5-tree-item-custom
				hide-selection-element
				type="Active"
				level="3"
			>
				<ui5-button slot="content">Level 3</ui5-button>
			</ui5-tree-item-custom>
		</ui5-tree-item-custom>
	</ui5-tree-item-custom>
</ui5-tree>

Overview

The ui5-tree component provides a tree structure for displaying data in a hierarchy.

Usage

When to use:

  • To display hierarchically structured items.
  • To select one or more items out of a set of hierarchically structured items.

When not to use:

  • To display items not hierarchically strcutured. In this case, use the List component.
  • To select one item from a very small number of non-hierarchical items. Select or ComboBox might be more appropriate.
  • The hierarchy turns out to have only two levels. In this case, use List with group items.

Keyboard Handling

The ui5-tree provides advanced keyboard handling. The user can use the following keyboard shortcuts in order to navigate trough the tree:
  • [UP/DOWN] - Navigates up and down the tree items that are currently visible.
  • [RIGHT] - Drills down the tree by expanding the tree nodes.
  • [LEFT] - Goes up the tree and collapses the tree nodes.

The user can use the following keyboard shortcuts to perform selection, when the mode property is in use:
  • [SPACE] - Selects the currently focused item upon keyup.
  • [ENTER] - Selects the currently focused item upon keydown.

ES6 Module Import

import "@ui5/webcomponents/dist/Tree.js";
import "@ui5/webcomponents/dist/TreeItem.js";

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.8.0
accessibleNameRef
accessible-name-ref
string
""
Defines the IDs of the elements that label the component.
since v1.8.0
footerText
footer-text
string
""
Defines the component footer text.
headerText
header-text
string
""
Defines the component header text.

Note: If the header slot is set, this property is ignored.
mode
ListMode
"None"
Defines the mode of the component. Since the tree uses a ui5-list to display its structure, the tree modes are exactly the same as the list modes, and are all applicable.

Note:
  • None
  • SingleSelect
  • SingleSelectBegin
  • SingleSelectEnd
  • MultiSelect
  • Delete
noDataText
no-data-text
string
""
Defines the text that is displayed when the component contains no items.

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. Tree items may have other tree items as children.

Note: Use ui5-tree-item for the intended design.
header
HTMLElement [0..n]
Defines the component header.

Note: When the header slot 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 a tree item is activated.
item
type: HTMLElement
description: The clicked item.
item-delete
Fired when the Delete button of any tree 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-mouseout
Fired when the mouse cursor leaves the tree item borders.
since v1.0.0-rc.16
item
type: HTMLElement
description: the hovered item.
item-mouseover
Fired when the mouse cursor enters the tree item borders.
since v1.0.0-rc.16
item
type: HTMLElement
description: the hovered item.
item-toggle
Fired when a tree item is expanded or collapsed. Note: You can call preventDefault() on the event object to suppress the event, if needed. This may be handy for example if you want to dynamically load tree items upon the user expanding a node. Even if you prevented the event's default behavior, you can always manually call toggle() on a tree item.
item
type: HTMLElement
description: the toggled item.
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.
targetItem
type: HTMLElement
description: The item triggering the event.

Methods

This Web Component exposes public methods. You can invoke them directly on the Web Component instance.

Name
Description
walk
Perform Depth-First-Search walk on the tree and run a callback on each node
callback
type: function
description: function to execute on each node of the tree with 3 arguments: the node, the level and the index

TreeItem

Overview

The ui5-tree-item represents a node in a tree structure, shown as a ui5-list.
This is the item to use inside a ui5-tree. You can represent an arbitrary tree structure by recursively nesting tree items.

CSS Shadow Parts

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

ES6 Module Import

import "@ui5/webcomponents/dist/TreeItem.js";

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
additionalText
additional-text
string
""
Defines the additionalText, displayed in the end of the tree 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
text
string
""
Defines the text of the tree item.
accessibleName
accessible-name
string
Defines the accessible name of the component.
since v1.8.0
expanded
boolean
false
Defines whether the tree list item will show a collapse or expand icon inside its toggle button.
hasChildren
has-children
boolean
false
Defines whether the tree node has children, even if currently no other tree nodes are slotted inside.
Note: This property is useful for showing big tree structures where not all nodes are initially loaded due to performance reasons. Set this to true for nodes you intend to load lazily, when the user clicks the expand button. It is not necessary to set this property otherwise. If a tree item has children, the expand button will be displayed anyway.
icon
string
""
If set, an icon will be displayed before the text of the tree list item.
indeterminate
boolean
false
Defines whether the selection of a tree node is displayed as partially selected.

Note: The indeterminate state can be set only programmatically and can’t be achieved by user interaction, meaning that the resulting visual state depends on the values of the indeterminate and selected properties:
  • If a tree node has both selected and indeterminate set to true, it is displayed as partially selected.
  • If a tree node has selected set to true and indeterminate set to false, it is displayed as selected.
  • If a tree node has selected set to false, it is displayed as not selected regardless of the value of the indeterminate property.

Note: This property takes effect only when the ui5-tree is in MultiSelect mode.
since v1.1.0
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
sap.ui.webc.main.ITreeItem [0..n]
Defines the items of the component.

Note: Use ui5-tree-item or ui5-tree-item-custom
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.

Methods

This Web Component exposes public methods. You can invoke them directly on the Web Component instance.

Name
Description
toggle
Call this method to manually switch the expanded state of a tree item.

TreeItemCustom

The ui5-tree-item-custom represents a node in a tree structure, shown as a ui5-list.
This is the item to use inside a ui5-tree. You can represent an arbitrary tree structure by recursively nesting tree items. You can use this item to put any custom content inside the tree item.

CSS Shadow Parts

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

ES6 Module Import

import "@ui5/webcomponents/dist/TreeItemCustom.js";

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
hideSelectionElement
hide-selection-element
Boolean
false
Defines whether the tree list item should display the selection element.
accessibleName
accessible-name
string
Defines the accessible name of the component.
since v1.8.0
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
expanded
boolean
false
Defines whether the tree list item will show a collapse or expand icon inside its toggle button.
hasChildren
has-children
boolean
false
Defines whether the tree node has children, even if currently no other tree nodes are slotted inside.
Note: This property is useful for showing big tree structures where not all nodes are initially loaded due to performance reasons. Set this to true for nodes you intend to load lazily, when the user clicks the expand button. It is not necessary to set this property otherwise. If a tree item has children, the expand button will be displayed anyway.
icon
string
""
If set, an icon will be displayed before the text of the tree list item.
indeterminate
boolean
false
Defines whether the selection of a tree node is displayed as partially selected.

Note: The indeterminate state can be set only programmatically and can’t be achieved by user interaction, meaning that the resulting visual state depends on the values of the indeterminate and selected properties:
  • If a tree node has both selected and indeterminate set to true, it is displayed as partially selected.
  • If a tree node has selected set to true and indeterminate set to false, it is displayed as selected.
  • If a tree node has selected set to false, it is displayed as not selected regardless of the value of the indeterminate property.

Note: This property takes effect only when the ui5-tree is in MultiSelect mode.
since v1.1.0
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
content
HTMLElement [0..n]
Defines the content of the ui5-tree-item.
default
sap.ui.webc.main.ITreeItem [0..n]
Defines the items of the component.

Note: Use ui5-tree-item or ui5-tree-item-custom
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.

Methods

This Web Component exposes public methods. You can invoke them directly on the Web Component instance.

Name
Description
toggle
Call this method to manually switch the expanded state of a tree item.
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