Tree

lightning:tree

Displays a nested tree. This component requires API version 41.0 and later.

For Aura components only. For LWC development, use lightning-tree.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

A lightning:tree component displays visualization of a structural hierarchy, such as a sitemap for a website or a role hierarchy in an organization. Items are displayed as hyperlinks and items in the hierarchy can be nested. Items with nested items are also known as branches.

This component implements styling from trees in the Lightning Design System.

To create a tree, pass in an array of key-value pairs to the items attribute.

Key	Type	Description
label	string	Required. The title and label for the hyperlink.
metatext	string	Text to provide users with supplemental information and aid with identification or disambiguation.
items	object	Nested items as an array of key-value pairs.
name	string	The unique name for the item for the `onselect` event handler to return the tree item that was clicked.
href	string	The URL for the link.
expanded	boolean	Specifies whether a branch is expanded. An expanded branch displays its nested items visually. The default is false.
disabled	boolean	Specifies whether an item is disabled. A disabled item is grayed out and can’t be focused or perform any action. The default is false.

Here’s an example of a tree with more than one level of nesting.

1<aura:component>
2  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
3  <aura:attribute name="items" type="Object" />
4  <lightning:tree items="{! v.items }" header="Roles" />
5</aura:component>

The tree is created during component initialization.

1({
2  doInit: function (cmp, event, helper) {
3    var items = [
4      {
5        label: "Western Sales Director",
6        name: "1",
7        expanded: true,
8        items: [
9          {
10            label: "Western Sales Manager",
11            name: "2",
12            expanded: true,
13            items: [
14              {
15                label: "CA Sales Rep",
16                name: "3",
17                expanded: true,
18                items: [],
19              },
20              {
21                label: "OR Sales Rep",
22                name: "4",
23                expanded: true,
24                items: [],
25              },
26            ],
27          },
28        ],
29      },
30      {
31        label: "Eastern Sales Director",
32        name: "5",
33        expanded: false,
34        items: [
35          {
36            label: "Easter Sales Manager",
37            name: "6",
38            expanded: true,
39            items: [
40              {
41                label: "NY Sales Rep",
42                name: "7",
43                expanded: true,
44                items: [],
45              },
46              {
47                label: "MA Sales Rep",
48                name: "8",
49                expanded: true,
50                items: [],
51              },
52            ],
53          },
54        ],
55      },
56    ];
57    cmp.set("v.items", items);
58  },
59});

To retrieve the selected item Id, use the onselect attribute and bind it to your event handler, which is shown by handleSelect() in the next example. The select event is also fired when you select an item with an href value.

1({
2  handleSelect: function (cmp, event, helper) {
3    //return name of selected tree item
4    var myName = event.getParam("name");
5    alert("You selected: " + myName);
6  },
7});

You can add or remove items in a tree. Let’s say you have a tree that looks like this.

1var items = [
2  {
3    label: "Go to Record 1",
4    href: "#record1",
5    items: [],
6  },
7  {
8    label: "Go to Record 2",
9    href: "#record2",
10    items: [],
11  },
12  {
13    label: "Go to Record 3",
14    href: "#record3",
15    items: [],
16  },
17];

This example adds a nested item at the end of the tree.

1({
2  addItem: function (cmp, event, helper) {
3    var items = cmp.get("v.items");
4    var branch = items.length - 1;
5    var label = "New item added at " + branch;
6    var newItem = {
7      label: label,
8      expanded: true,
9      disabled: false,
10      items: [],
11    };
12    items[branch].items.push(newItem);
13    cmp.set("v.items", items);
14    alert("Added new item at branch: " + branch);
15  },
16});

When providing an href value to an item, the onselect event handler is triggered before navigating to the hyperlink.

Selecting a Tree Item Programmatically

To select a tree item using JavaScript, pass in the tree item name using selectedItem.

This example selects the “United States Sales” tree item on load. Press the “Change Selected” button to select the “Americas” tree item.

1<aura:component>
2  <aura:handler name="init" value="{!this}" action="{!c.init}" />
3  <aura:attribute name="items" type="Object" />
4
5  <lightning:tree items="{!v.items }" selectedItem="{!v.selected }" />
6  <lightning:button label="Change Selected" onclick="{!c.handleClick}" />
7</aura:component>

Define the items in your JavaScript code and pass in the selected item name.

1({
2  doInit: function (cmp, event, helper) {
3    var items = [
4      {
5        label: "Asia Pacific Sales",
6        name: "Asia Pacific Sales",
7        items: [
8          {
9            label: "Asia Sales",
10            name: "Asia Sales",
11            items: [],
12          },
13        ],
14      },
15      {
16        label: "Europe Sales",
17        name: "Europe Sales",
18        items: [
19          {
20            label: "UK Sales",
21            name: "UK Sales",
22            items: [],
23          },
24          {
25            label: "EU Sales",
26            name: "EU Sales",
27            items: [],
28          },
29        ],
30      },
31      {
32        label: "Americas",
33        name: "Americas",
34        items: [
35          {
36            label: "Northern America Sales",
37            name: "Northern America Sales",
38            items: [
39              {
40                label: "United States Sales",
41                name: "United States Sales",
42                items: [],
43              },
44            ],
45          },
46        ],
47      },
48    ];
49    cmp.set("v.items", items);
50    cmp.set("v.selected", "United States Sales");
51  },
52
53  handleClick: function (cmp, event, helper) {
54    cmp.set("v.selected", "Americas");
55  },
56});

Expanding and Collapsing A Branch

To expand and collapse a branch programmatically, get the tree items and update the expanded attribute.

1var myitems = cmp.find("mytree").get("v.items");
2
3// expand the first branch
4myitems[0].expanded = true;
5
6// collapse the first branch
7myitems[0].expanded = false;
8
9// replace the tree items with the latest expanded state
10cmp.set("v.items", myitems);

Design Guidelines

Use lightning:tree if your app has layered navigation that can’t be represented in a simple tab set. A tree helps users navigate to pages and quickly find a nested child page without loading each page.

You can use lightning:tree with lightning:breadcrumbs to further help users navigate the hierarchy.

Trees can have unlimited nesting, but we recommend flatter trees as they are generally easier to navigate.

Not all items in the list need a corresponding page. Instead, you can group related pages together using a label header without providing an unnecessary landing page.

Accessibility

You can use the keyboard to navigate the tree. Tab into the tree and use the Up and Down Arrow key to focus on tree items. To collapse an expanded branch, press the Left Arrow key. To expand a branch, press the Right Arrow key. Pressing the Enter key or Space Bar is similar to an onclick event, and performs the default action on the item.

Attributes

Name	Description	Type	Default
body	The body of the component. In markup, this is everything in the body of the tag.	Aura.Component[]
class	A CSS class for the outer element, in addition to the component's base classes.	String
header	The text that's displayed as the tree heading.	String	0
items	An array of key-value pairs that describe the tree. Keys include label, name, disabled, expanded, and items.	Object	base
onselect	The action triggered when a tree item is selected.	Aura.Action
selectedItem	Selects and highlights the specified tree item. Tree item names are case-sensitive. If the tree item is nested, selecting this item also expands the parent branches.	String
title	Displays tooltip text when the mouse moves over the element.	String