lightning:tree

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

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 inherits 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.
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 a branch is disabled. A disabled branch can't be expanded. The default is false.

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

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

The tree is created during component initialization.

({
    doInit: function (cmp, event, helper) {
    var items = [{
            "label": "Western Sales Director",
            "name": "1",
            "expanded": true,
            "items": [{
                "label": "Western Sales Manager",
                "name": "2",
                "expanded": true,
                "items" :[{
                    "label": "CA Sales Rep",
                    "name": "3",
                    "expanded": true,
                    "items" : []
                },{
                    "label": "OR Sales Rep",
                    "name": "4",
                    "expanded": true,
                    "items" : []
                }]
            }]
        }, {
            "label": "Eastern Sales Director",
            "name": "5",
            "expanded": false,
            "items": [{
                "label": "Easter Sales Manager",
                "name": "6",
                "expanded": true,
                "items" :[{
                    "label": "NY Sales Rep",
                    "name": "7",
                    "expanded": true,
                    "items" : []
                }, {
                    "label": "MA Sales Rep",
                    "name": "8",
                    "expanded": true,
                    "items" : []
                }]
            }]
        }];
        cmp.set('v.items', items);
    }     
})

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.

({
    handleSelect: function (cmp, event, helper) {
        //return name of selected tree item
        var myName = event.getParam('name');
        alert("You selected: " + myName);
    }
})

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

var items = [{
            label: "Go to Record 1",
            href: "#record1",
            items: []
        },{
            label: "Go to Record 2",
            href: "#record2",
            items: []
        }, {
            label: "Go to Record 3",
            href: "#record3",
            items: []
        }];

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

({
    addItem: function (cmp, event, helper) {
        var items = cmp.get('v.items');
        var branch = items.length - 1;
        var label = 'New item added at ' + branch;
        var newItem = {
            label: label,
            expanded: true,
            disabled: false,
            items: []
        };
        items[branch].items.push(newItem);
        cmp.set('v.items', items);
        alert("Added new item at branch: " + branch);
    }
})

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

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

Attribute Name Attribute type Description Required?
body Component[] The body of the component. In markup, this is everything in the body of the tag.
class String A CSS class for the outer element, in addition to the component's base classes.
title String Displays tooltip text when the mouse moves over the element.
items Object An array of key-value pairs that describe the tree. Keys include label, name, disabled, expanded, and items.
header String The text that's displayed as the tree heading.
onselect Action The action triggered when a tree item is selected.