Skip to main content

Tree

<ui5-tree> | Since 1.0.0-rc.8

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 structured. 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] or [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 selectionMode 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";

Basic Sample

Properties

selectionMode

DescriptionDefines the selection 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.
Type"None" | "Single" | "SingleStart" | "SingleEnd" | "SingleAuto" | "Multiple" | "Delete" | undefined
Default"None"

noDataText

DescriptionDefines the text that is displayed when the component contains no items.
Typestring | undefined
Defaultundefined

headerText

DescriptionDefines the component header text.
Note: If the header slot is set, this property is ignored.
Typestring | undefined
Defaultundefined

footerText

DescriptionDefines the component footer text.
Typestring | undefined
Defaultundefined

accessibleName

DescriptionDefines the accessible name of the component.
Typestring | undefined
Defaultundefined
Since1.8.0

accessibleNameRef

DescriptionDefines the IDs of the elements that label the component.
Typestring | undefined
Defaultundefined
Since1.8.0

accessibleDescription

DescriptionDefines the accessible description of the component.
Typestring | undefined
Defaultundefined
Since2.5.0

accessibleDescriptionRef

DescriptionDefines the IDs of the elements that describe the component.
Typestring | undefined
Defaultundefined
Since2.5.0

Slots

default

DescriptionDefines the items of the component. Tree items may have other tree items as children.
Note: Use ui5-tree-item for the intended design.
TypeArray<TreeItemBase>
DescriptionDefines the component header.
Note: When the header slot is set, the headerText property is ignored.
TypeArray<HTMLElement>

Events

item-toggle

DescriptionFired 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.
TypeCustomEvent<TreeItemToggleEventDetail>
Parametersitem: HTMLElement
the toggled item.
BubblesYes
CancelableYes - via preventDefault()

item-mouseover

DescriptionFired when the mouse cursor enters the tree item borders.
TypeCustomEvent<TreeItemMouseoverEventDetail>
Parametersitem: HTMLElement
the hovered item.
Since1.0.0-rc.16
BubblesYes
CancelableNo

item-mouseout

DescriptionFired when the mouse cursor leaves the tree item borders.
TypeCustomEvent<TreeItemMouseoutEventDetail>
Parametersitem: HTMLElement
the hovered item.
Since1.0.0-rc.16
BubblesYes
CancelableNo

item-click

DescriptionFired when a tree item is activated.
TypeCustomEvent<TreeItemClickEventDetail>
Parametersitem: HTMLElement
The clicked item.
BubblesYes
CancelableYes - via preventDefault()

item-delete

DescriptionFired when the Delete button of any tree item is pressed.
Note: A Delete button is displayed on each item, when the component selectionMode property is set to Delete.
TypeCustomEvent<TreeItemDeleteEventDetail>
Parametersitem: HTMLElement
the deleted item.
BubblesYes
CancelableNo

selection-change

DescriptionFired when selection is changed by user interaction in Single, SingleStart, SingleEnd and Multiple modes.
TypeCustomEvent<TreeSelectionChangeEventDetail>
ParametersselectedItems: Array
An array of the selected items.
previouslySelectedItems: Array
An array of the previously selected items.
targetItem: HTMLElement
The item triggering the event.
BubblesYes
CancelableNo

move

DescriptionFired when a movable tree item is moved over a potential drop target during a drag-and-drop operation.
If the new position is valid, prevent the default action of the event using preventDefault().
TypeCustomEvent<TreeMoveEventDetail>
Parameterssource: object
Contains information about the moved element under the element property.
destination: object
Contains information about the destination of the moved element. Has element and placement properties.
BubblesYes
CancelableNo

move-over

DescriptionFired when a movable tree item is dropped onto a drop target.
Note: The move event is fired only if there was a preceding move-over event with prevented default action.
TypeCustomEvent<TreeMoveEventDetail>
Parameterssource: object
Contains information about the moved element under the element property.
destination: object
Contains information about the destination of the moved element. Has element and placement properties.
BubblesYes
CancelableYes - via preventDefault()

Methods

walk

DescriptionPerform Depth-First-Search walk on the tree and run a callback on each node
Return typevoid
Parameterscallback: WalkCallback
function to execute on each node of the tree with 3 arguments: the node, the level and the index

CSS Parts

No CSS parts available for this component.

More Samples

Custom Tree Items

Drag And Drop

The tree items are draggable through the use of the movable property on TreeItem.