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-busyindicator 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-busyindicator>

<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>
	

Overview

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

Keyboard Handling

ui5-tree provides advanced keyboard handling. You can use the up/down arrow keys to navigate to the previous/next item in the list, representing the tree, regardless of nesting, but also the left/right arrow keys to drill down and go up the tree. If you press the right arrow on a tree node, it will expand, if not expanded. If you press the right arrow key once more, the first child of this node will be selected. If you press the left arrow on a tree node, it will collapse, if expanded. If you press the left arrow key once more, the parent node of this tree node will be selected.

ES6 Module Import

import @ui5/webcomponents/dist/Tree.js";
import @ui5/webcomponents/dist/TreeItem.js"; (for its respective item element)

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
_minimal
undefined
Represents the tree in a very minimal state - icons only with no text and no toggle buttons
since v1.0.0-rc.8
_toggleButtonEnd
_toggle-button-end
undefined
Shows the toggle button at the end, rather than at the beginning of the items
since v1.0.0-rc.8
footerText
footer-text
string
""
Defines the ui5-tree footer text.
headerText
header-text
string
""
Defines the ui5-tree header text.

Note: If the header slot is set, this property is ignored.
mode
ListMode
"None"
Defines the mode of the ui5-tree. 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: Available options are None, SingleSelect, SingleSelectBegin, SingleSelectEnd, MultiSelect, and Delete.
noDataText
no-data-text
string
""
Defines the text that is displayed when the ui5-tree 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 ui5-tree. Tree items may have other tree items as children.

Note: Use ui5-tree-item for the intended design.
header
HTMLElement [0..n]
Defines the ui5-tree 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 ui5-tree mode property is set to Delete.
item
type: HTMLElement
description: the deleted 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.

Methods

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

Name
Description
_getListItemForTreeItem
Returns the corresponding list item for a given tree item
item
type: undefined
description: The tree item
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 2 arguments: the node and the level

TreeItem

Overview

This is the item to use inside a ui5-tree. You can represent an arbitrary tree structure by recursively nesting tree items.

Usage

ui5-tree-item is an abstract element, representing a node in a ui5-tree. The tree itself is rendered as a list, and each ui5-tree-item is represented by a list item(ui5-li-tree) in that list. Therefore, you should only use ui5-tree-item directly in your apps. The ui5-li-tree list item is internal for the list, and not intended for public use.

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
expanded
boolean
false
Defines whether the tree node is expanded or collapsed. Only has visual effect for tree nodes with children.
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, representing the tree item.
selected
boolean
false
Defines whether the tree node is selected by the user. Only has effect if the ui5-tree is in one of the following modes: in SingleSelect, SingleSelectBegin, SingleSelectEnd and MultiSelect.
text
String
""
Defines the text of the tree item.

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 this ui5-tree-item.
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