Tree

lightning-tree

Displays a nested tree.

For Use In

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

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

Design

lightning-tree implements the trees blueprint in the Salesforce Lightning Design System (SLDS). The trees adapt to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

	SLDS 1	SLDS 2
Design	Trees	Trees
For Use In	Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline	Lightning Experience

Usage

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. To retrieve the selected item ID, use the onselect event handler. The select event is also fired when you select an item with an href value.

1<template>
2    <lightning-tree items={treeList} onselect={handleSelect}>
3    </lightning-tree>
4</template>

Define the tree items in your JavaScript file. Use the detail property to retrieve the name of the selected tree item.

1import { LightningElement } from "lwc";
2
3const 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: "Eastern 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
58const mapping = {
59  1: "Western Sales Director",
60  2: "Western Sales Manager",
61  3: "CA Sales Rep",
62  4: "OR Sales Rep",
63  5: "Eastern Sales Director",
64  6: "Eastern Sales Manager",
65  7: "NY Sales Rep",
66  8: "MA Sales Rep",
67};
68
69export default class TreeExample extends LightningElement {
70  treeList = items;
71  selected = "";
72
73  handleSelect(event) {
74    //set the name of selected tree item
75    this.selected = mapping[event.detail.name];
76  }
77}

Add or Remove Items in a Tree

You can add or remove items in a tree. Let’s say you have a tree that looks like this, with a button to add a nested item to the tree.

1<template>
2    <lightning-button
3        label="Add to Tree"
4        id="change-button"
5        onclick={handleClick}
6    >
7    </lightning-button>
8    <lightning-tree items={treeList}> </lightning-tree>
9</template>

Define the items in your JavaScript code.

1import { LightningElement } from "lwc";
2
3const items = [
4  {
5    label: "Go to Record 1",
6    href: "#record1",
7    items: [],
8    expanded: true,
9  },
10  {
11    label: "Go to Record 2",
12    href: "#record2",
13    items: [],
14    expanded: true,
15  },
16  {
17    label: "Go to Record 3",
18    href: "#record3",
19    items: [],
20    expanded: true,
21  },
22];
23
24export default class AddRemoveExample extends LightningElement {
25  treeList = items;
26}

This example handleClick() function adds a nested item at the end of the tree when the button is clicked.

1export default class AddRemoveExample extends LightningElement {
2  treeList = items;
3
4  handleClick(e) {
5    const newItems = Array.from(this.treeList);
6    const branch = newItems.length;
7    const label = "New item added at Record" + branch;
8    const newItem = {
9      label: label,
10      expanded: true,
11      disabled: false,
12      items: [],
13    };
14    newItems[branch - 1].items.push(newItem);
15    this.treeList = newItems;
16  }
17}

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

Select a Tree Item Programmatically

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

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

1<template>
2    <lightning-tree
3        items={treeList}
4        selected-item={selected}
5    ></lightning-tree>
6    <lightning-button
7        label="Change Selected"
8        onclick={handleClick}
9    ></lightning-button>
10</template>

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

1import { LightningElement } from "lwc";
2
3const 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
50export default class SelectItemExample extends LightningElement {
51  treeList = items;
52  selected = "United States Sales";
53
54  handleClick() {
55    this.selected = "Americas";
56  }
57}

Expand or Collapse A Branch

To expand or collapse a branch programmatically, get the tree items and update its expanded property.

1// expand the first branch
2this.template.querySelector("lightning-tree").items[0].expanded = true;
3
4// collapse the first branch
5this.template.querySelector("lightning-tree").items[0].expanded = false;

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

Custom Events

select

The event fired when a tree item is selected and before navigating to a given hyperlink.

The select event returns the following parameter.

Parameter	Type	Description
name	string	The label of the selected tree item.

The event properties are as follows.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	true	This event can be canceled. You can call `preventDefault()` on this event.
composed	true	This event propagates outside of the component in which it was dispatched.

LWC Recipes

The LWC Recipes GitHub repository contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses lightning-tree, see the c-wire-get-picklist-values-by-record-type component in the LWC Recipes repo.

Attributes

Name	Description	Type	Default
header	The text that's displayed as the tree heading.	string
heading-level	Changes the 'aria-level' attribute value for the <h2> markup tag in the card's title element. Supported values are (1, 2, 3, 4, 5, 6).	string \| number	2
items	An array of key-value pairs that describe the tree. See the Documentation tab for more information.	array
selected-item	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