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>
	

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

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 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
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
ValueState
"None"
Defines the state of the additionalText.
Available options are: "None" (by default), "Success", "Warning", "Information" and "Erorr".
since v1.0.0-rc.15
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
sap.ui.webcomponents.main.ITreeItem [0..n]
Defines the items of this component.
Theme: Quartz Light Quartz Dark Quartz High Contrast Black Quartz High Contrast White Belize High Contrast Black High Contrast White Horizon
Content Density: Cozy Compact
Text Direction: LTR RTL
Apply Cancel