> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/dynamic-components/components/tree.md).

# Tree

The Avonni Tree component displays hierarchical data as an expandable and collapsible tree structure. Use it to let users navigate nested records, categories, or any parent-child relationship — with optional multi-selection and checkboxes.

## Overview

The Tree component comes in two presets in the Component Builder:

* **Tree** — a standard expandable tree for navigating hierarchical data. Users click nodes to expand or collapse branches and trigger interactions.
* **Checkbox Tree** — enables multi-selection with a checkbox displayed next to each node. Useful for category filters, permission selectors, or any scenario where users need to pick multiple items from a hierarchy.

Both presets use the same component and configuration panel; the **Checkbox Tree** preset simply starts with **Is Multi Select** turned on.

## Configuration

To configure the Tree, select it on the canvas. The **Edit Tree** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.

### Data Source

Before building your tree, you must tell the component where to get the data it should display. There are three options:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Manual</strong></td><td>Enter data directly into the component configuration. Each item can include nested child items for multi-level hierarchies.</td><td><a href="/dynamic-components/component-builder/data-sources/manual.md">Manual</a></td></tr><tr><td><strong>Picklist</strong></td><td>Retrieve data dynamically from a standard or custom picklist field within Salesforce.</td><td></td></tr><tr><td><strong>Query</strong></td><td>Fetch data from related Salesforce objects using nested queries, enabling multi-level hierarchies from real records.</td><td><a href="/dynamic-components/component-builder/data-sources/nested-queries.md">Nested Queries</a></td></tr></tbody></table>

### Adding a nested level

With the **Query** data source, the tree's levels come from a nested query, and there are two different ways to add a query. They are easy to confuse because both produce a valid editor.

* The **Add Item** button under the Items list always creates another **top level** query. Its object picker offers any object in your org, and it never offers child records.
* The **Add** action on an item you have already created adds a level **underneath that item**. Its object picker is built from the child relationships of the parent object, so this is where your child records appear.

If you are looking at a picker that offers every object and no children, you are on a top level query. Go back to the item you want to nest under and use its own **Add** action instead.

A nested level needs two things: the child object, and the **relationship field** that links it back to its parent. If you pick only the object, the editor tells you that a relationship field is still missing.

If the object you expect is not in the list, turn on the **All Objects** toggle at the top of the picker. The list is filtered by default.

### Data Mapping

When using a dynamic data source (Query or Picklist), configure the **Data Mappings** section to tell the component how to map fields to tree node attributes.

For each level in your hierarchy, map at minimum:

* **Label** — the text displayed for each node (e.g., the record Name field).
* **Key Field** — a unique identifier for each node (e.g., the record Id).
* **Metatext** — optional supplemental text to help users identify or disambiguate a node.

{% hint style="warning" %}
**Important Note for Query Data Source**

To use the Query data source, you *must* structure your query as a *nested query*, even if you only display a single level of data (i.e. even if there isn't a true parent-child relationship). The top level of the nested query represents your primary data, and you can optionally add child queries for deeper levels of the tree. This differs from a standard query.
{% endhint %}

{% hint style="warning" %}
**Note on the recordings on this page**

The Nested Queries interface has changed since the recordings on this page were captured. The written steps are current; the videos still show the earlier layout, so follow the text wherever the two differ.
{% endhint %}

{% @arcade/embed url="<https://app.arcade.software/share/kThBCDpa9aWmKcckM3dh>" flowId="kThBCDpa9aWmKcckM3dh" %}

### Content

#### Header

The text displayed as the tree heading, shown above the root nodes. Leave blank to show no header.

#### Header Icon Name

A Lightning Design System icon displayed to the left of the header text (e.g., `utility:folder`). If a **Header Image Source** is also set, the image takes priority over this icon.

#### Header Icon Size

Controls the size of the header icon. Options: **Xxs**, **Xs**, **Small** (default), **Medium**, **Large**. Requires: **Header Icon Name** to be set.

#### Header Image Source

The URL of an image displayed to the left of the header. Accepts common web image formats (PNG, JPG, SVG, GIF, WebP, etc.). If provided, it takes priority over **Header Icon Name**.

#### Is Multi Select

When enabled, multiple tree nodes can be selected simultaneously and a checkbox appears to the left of each node. This is the key setting that distinguishes the **Checkbox Tree** preset from the standard **Tree** preset.

#### Independent Multi Select

When enabled, parent and child nodes are selected independently — selecting a parent does not automatically select or deselect its children. Requires: **Is Multi Select** to be enabled.

#### Show Item Count

When enabled, the number of child nodes is displayed in parentheses next to each parent node label (e.g., "Accounts (5)").

#### Collapse Disabled

When enabled, all branches remain expanded and users cannot collapse them. This is useful when you want to always show the full hierarchy without interaction.

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Use Cases

### Example: Displaying Related Contacts under Accounts

This example shows how to display a tree where Accounts are the parent nodes, and their related Contacts are the child nodes. This uses a **Nested Query** to retrieve both Accounts and Contacts efficiently.

#### 1. Create a Nested Query

* **Parent Object:**
  * Add your first query and select `Account` as the **Object**.
  * Add filters if needed.
  * Do the Data Mappings with the Label and Metatext attribute.
* **Child Object:**
  * Use the **Add** action on the Account item you just created. Do not use the **Add Item** button under the list: that one would create a second top level query rather than a child level.
  * Select `Contact` as the **Object**, then select the **relationship field** that links Contact back to Account.
  * Do the Data Mappings with the Label and Metatext attribute.

{% @arcade/embed url="<https://app.arcade.software/share/ZLmn8KHIfrRXhg6Fmnsc>" flowId="ZLmn8KHIfrRXhg6Fmnsc" %}

Now, the Tree component displays Accounts as parent nodes. Expanding an Account node reveals its related Contacts as child nodes.

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Tree. Configure them from the **Interactions** tab of the Edit Tree panel.

### Item Click

Fires when a user clicks a tree node. Use the **targetName** output to identify which node was clicked, and use **clickedItem**, **clickedItemRecordId**, or **clickedItemSObject** to drive downstream actions such as navigating to a record, setting a variable, or launching a flow.

## Styling

The **Style** tab gives you fine-grained control over the Tree's appearance. Configure it from the **Style** tab of the Edit Tree panel.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the entire tree.

* **Top / Right / Bottom / Left:** Adjust the space on each side of the tree.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing of the tree container.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Size" %}
Controls the tree's dimensions.

* **Width / Height:** Set fixed dimensions for the tree.
* **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds.
* **Overflow / Overflow X / Overflow Y:** Control how content that exceeds the bounds is handled.
  {% endtab %}

{% tab title="Header" %}
Styles the tree's header text and image.

* **Header:** Color / Font Size / Font Style / Font Weight.
* **Image:** Object Fit / Height / Width.
  {% endtab %}

{% tab title="Item" %}
Styles the individual tree items, including their labels, metatext, and states.

* **Header Background Color / Hover:** Set the item label background color and its hover state.
* **Header Text Color / Disabled:** Control item label text color and disabled state color.
* **Header Link Color / Hover:** Style item labels that are links.
* **Header Font Size / Style / Weight:** Adjust item label typography.
* **Metatext Text Color / Disabled:** Style the supplemental metatext.
* **Metatext Line Clamp:** Limit the number of lines shown for metatext.
* **Background Color Hover / Selected:** Set item row background on hover and when selected.
* **Shadow Selected:** Apply a shadow to selected items.
* **Block Start / End / Inline Start / End:** Fine-tune item spacing.
  {% endtab %}
  {% endtabs %}

## Output Variables

The Tree exposes these output variables you can reference elsewhere on the page after the user interacts with it.

### Item Click

When a user clicks a tree node, these variables update with the clicked node's data.

| Output variable                   | Type             | What it returns                                                                                |
| --------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
| **Clicked Item**                  | Object           | The clicked node's data — its name, label, and sObject API name.                               |
| **Clicked Item Record Id**        | Text (String)    | The Salesforce record Id associated with the clicked node. Requires a **Query** data source.   |
| **Clicked Item sObject**          | Record (SObject) | The full Salesforce record associated with the clicked node. Requires a **Query** data source. |
| **Clicked Item sObject API Name** | Text (String)    | The API name of the Salesforce object associated with the clicked node.                        |

> **Example:** When a user clicks an Account node, use **Clicked Item sObject** to display the Account's details in a record-detail component beside the tree.

### Item Selection

When a user selects one or more tree nodes (multi-select mode), these variables update with the current selection.

| Output variable            | Type                           | What it returns                                                                                 |
| -------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
| **Selected Item Names**    | Text Collection                | The unique names of all currently selected tree nodes.                                          |
| **Selected Items sObject** | Record Collection (SObject\[]) | The full Salesforce records for all currently selected nodes. Requires a **Query** data source. |

> **Example:** When a user selects multiple Contact nodes in a Checkbox Tree, use **Selected Items sObject** to pass the selected records to a bulk-update flow.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/dynamic-components/components/tree.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.