> 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="/pages/p2RQTJ1oud3ALc4E5ott">/pages/p2RQTJ1oud3ALc4E5ott</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="/pages/nLmnEEgTMr9Ezh8Xhe92">/pages/nLmnEEgTMr9Ezh8Xhe92</a></td></tr></tbody></table>

### 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 Nested Query Steps**

Please be aware that the interface and options for configuring **Nested Queries** have been updated since this tutorial was created. While the core concepts remain the same, the specific steps shown below may differ from those in the current Avonni Component Builder. We are working on updating this guide shortly to reflect the latest enhancements.
{% 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

* **Add Query:** Add a new "Nested Query"
* **Parent Object:**
  * Select `Account` as the **Object**.
  * Add filters if needed.
  * Do the Data Mappings with the Label and Metatext attribute.
* **Child Object:**
  * Click "Add Child Object" by clicking on the little arrow next to the parent object name.
  * Select `Contact` as the **Object**.
  * 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.

* **Color:** Set the header text color.
* **Font Size:** Adjust the header text size.
* **Font Style:** Set the header font style (normal or italic).
* **Font Weight:** Control the header font weight.
  {% endtab %}

{% tab title="Header Image" %}
Styles the image displayed in the tree's header.

* **Object Fit:** Control how the header image fills its container.
* **Height / Width:** Set the dimensions of the header image.
  {% 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.