> 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/flow/flow-components/tree-grid.md).

# Tree Grid

The Tree Grid displays hierarchical records in an expandable, columnar table on a Flow screen, with configurable columns, row toggles, and selection.

The **Tree Grid** displays hierarchical (parent/child) records in an expandable, columnar table on a Flow screen. Rows expand and collapse to reveal nested items, with configurable columns, selection, and header actions.

## Overview

Use the Tree Grid when records have a parent/child relationship users should browse in place: a territory that opens onto its accounts, an account that opens onto its opportunities, a category that opens onto its products. For a flat list, or anything users mainly sort, filter and page through at length, use the Data Table instead.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FoVnHCNXgk69y1RwmUvPn%2Ftree-grid-hierarchy.png?alt=media" alt="A Tree Grid on a flow screen with one territory expanded down to its accounts, showing the open and the closed toggle icon"><figcaption><p>A territory hierarchy on a flow screen. The toggle in the first column shows its open icon on expanded rows and its closed icon on the rest.</p></figcaption></figure>

The rows come from one of two places: **rows you enter by hand** in the component, or **one Salesforce query per level** of the hierarchy. Either way the grid supports expandable rows, resizable and sortable columns, row selection, row and header actions, and loading more rows as the user scrolls.

***

## Set up a Tree Grid

From an empty screen to a live hierarchy, on the **Query** data source. Every setting named here has its full reference further down the page.

{% stepper %}
{% step %}

#### **Add the Tree Grid to the screen**

Drop it onto the screen, select it, and open the Component Builder.
{% endstep %}

{% step %}

#### **Choose the Query data source**

Open the **Data Source** section, at the bottom of the Properties tab, and choose **Query**.
{% endstep %}

{% step %}

#### **Query the top level**

Set **Object API Name** to the object the top rows read. **Filters**, **Order By** and **Maximum Number of Records** bound that query.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FPcVgRuMHSrvJfYx80ErY%2Ftree-grid-query-data-source.png?alt=media" alt="The Data Source section of the property editor with Query selected, showing the object, its filters and order by, and one child query under Items" width="320"><figcaption><p>The <strong>Query</strong> source. The top level reads Accounts; the entry under <strong>Items</strong> is a second query that loads each account's opportunities beneath it.</p></figcaption></figure>
{% endstep %}

{% step %}

#### **Add the levels below**

Under **Items**, click **Add Item** once per level below the top one. Each entry is a query of its own, and each names the **relationship field** that ties its records back to the level above. That field is what makes child records load under the right parent.
{% endstep %}

{% step %}

#### **Add the columns**

Under **Data Mappings**, add one entry per column you want to display. An Object Field column takes an **Object API Name** and a **Source Field**, and its **Type** is detected from the field you chose.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FmPv4V0DYh1LW9QQSfDDG%2Ftree-grid-column-settings.png?alt=media" alt="A column opened on its own settings: the Object Field and Custom switch, the object and source field, the Type set to Currency, and the type attributes below it" width="320"><figcaption><p>A column opened on its own settings. The <strong>Type</strong> decides what appears under <strong>Type Attributes</strong>: a Currency column gets its currency code and its digit settings.</p></figcaption></figure>
{% endstep %}

{% step %}

#### **Save and run the flow**

You get one row per top-level record, each with a toggle that opens the level below it.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
There is no **Key Field** to set with the Query source: the grid always keys on the record `Id`. **Key Field** is a Manual-only setting.
{% endhint %}

***

## Build a fixed hierarchy by hand

The **Manual** source keeps the rows inside the component, which suits a small, fixed hierarchy that does not come from the org. Fill the three properties in this order, because each one unlocks the next.

{% stepper %}
{% step %}

#### **Choose the Manual data source**

Open the **Data Source** section and choose **Manual**.
{% endstep %}

{% step %}

#### **Define the columns**

Under **Columns**, add one entry per column. Each takes a **Label**, the text shown in the column header, and a **Name**, the key that binds the column to your data. **Name** is required and rejects special characters.
{% endstep %}

{% step %}

#### **Pick the key field**

Set **Key Field** to the column whose values uniquely identify a row. It is required, and the **Data** property stays locked until you set it.
{% endstep %}

{% step %}

#### **Enter the rows and nest them**

In **Data**, enter one row per record, with one field per column you defined. To nest a row, open its action menu and choose **Add**: the new row is created as a child of the row you started from, as many levels deep as you need. The same menu offers **Edit**, **Move Up**, **Move Down**, and **Delete**.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2F1sH7HAvBCBE2YQ1XGwH1%2Ftree-grid-manual-data-source.png?alt=media" alt="The Data Source section of the property editor with Manual selected, showing the Columns list, the Key Field and the Data tree" width="320"><figcaption><p>The <strong>Manual</strong> source, with the three properties in the order you fill them.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Manual columns have no type setting, so every value renders as plain text. To format columns as currency, date, badge, avatar, and so on, use the **Query** data source and set the types in **Data Mappings**.
{% endhint %}

***

## Let users select rows

Selection is on from the start. What the flow does with it happens after the screen.

{% stepper %}
{% step %}

#### **Leave the checkbox column on**

**Hide Checkbox Column** removes the checkboxes and with them the ability to select rows, so leave it off.
{% endstep %}

{% step %}

#### **Show the row numbers and the count**

Turn on **Show Row Number Column** to number the rows, and **Show Number of Items Selected** to display a running count of the selection above the table.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FKn3kkwI7VzozoSNxY8kG%2Ftree-grid-selection.png?alt=media" alt="A Tree Grid with a leading row number column, selection checkboxes, two rows ticked and a count of the selection above the table"><figcaption><p>Row numbers, selection checkboxes, and the running count. The rows ticked here are the ones the <strong>Selected Rows</strong> output variables return.</p></figcaption></figure>
{% endstep %}

{% step %}

#### **Read the selection after the screen**

Select the screen element in Flow Builder, then the Tree Grid, then the output variable you need. **Selected Rows** carries the full records; the **Selected Rows Key Field Value** variants carry the keys alone, including one already formatted for a SOQL `IN` clause.
{% endstep %}
{% endstepper %}

***

## Let users act on a row

A row action is a column, not a setting: you add a column that holds the actions, then react to it on the Interactions tab.

{% stepper %}
{% step %}

#### **Add an Action column**

In **Data Mappings**, add a column and set its **Type** to **Action**.
{% endstep %}

{% step %}

#### **Define the actions**

Define the actions themselves in that column's **Type Attributes**. Each one carries the name the interaction targets.
{% endstep %}

{% step %}

#### **React on the Interactions tab**

On the **Interactions** tab, add a **Row Action Click** interaction and set its **Target Name** to the action you want to respond to. Each action gets its own interaction, so nothing has to branch on your side.
{% endstep %}

{% step %}

#### **Act on the record**

After the screen, use **Clicked Row Action Row** to act on the record whose action was clicked.
{% endstep %}
{% endstepper %}

Header actions work the same way, with **Header Action Click** and the **Actions** setting in the Header group.

***

## Data Source

| Data source                                                  | What it does                                                                                                                  |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| [**Manual**](/flow/component-builder/data-sources/manual.md) | Enter rows directly in the component configuration, nesting child rows under their parent. Best for small, fixed hierarchies. |
| [**Query**](/flow/component-builder/data-sources/query.md)   | Fetch records from Salesforce so child records load beneath their parent. The usual choice for live data.                     |

### Data Mappings

Available with the **Query** data source. Add one entry per column you want to display, and configure it with the following properties.

* **Object Field / Custom**: choose whether the column reads a Salesforce field or is a custom column you populate yourself, such as a button or an action menu.
* **Object API Name** and **Source Field**: for an Object Field column, the object and the field that populate the column.
* **Custom Label** and **Label**: turn on **Custom Label** to enter your own header text. Left off, the column uses the Salesforce field label.
* **Name**: for a Custom column, the key that identifies it. An Object Field column takes its key from the source field instead.
* **Type**: how the value is formatted (Text, Number, Currency, Date, Badge, Avatar, Button, Action, and more). It is detected from the field, and you can override it.
* **Type Attributes**: the settings specific to the chosen type, such as the currency code for a Currency column or the list of row actions for an Action column.
* **Cell Attributes**: alignment, and an optional icon shown in the cell.
* **Icon Name**: an icon displayed in the column header.
* **Sortable**: lets users sort the grid on this column.
* **Hidden**: keeps the column in the configuration without displaying it.
* **Initial Width** and **Wrap Text**: the column's starting width in pixels, and whether long values wrap instead of being truncated.

***

## Configuration

To configure the Tree Grid, click the component on the Flow screen. The **Edit Tree Grid Component** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below are the Properties tab, in the order the panel shows them. The **Data Source** and **Data Mappings** sections above sit at the bottom of that same tab, under **No Results Message**.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FyAonmWJrjUaj15eVD2TZ%2Ftree-grid-properties.png?alt=media" alt="The Properties tab of the property editor, showing the display toggles, the open Header group, and the collapsed Row Toggle Icon, Column Widths, Pagination, Sort, No Results Message and Data Source groups" width="320"><figcaption><p>The Properties tab. <strong>Row Number Offset</strong> is absent here because <strong>Show Row Number Column</strong> is off, and <strong>Data Source</strong> sits last, under <strong>No Results Message</strong>.</p></figcaption></figure>

### Properties

* **Hide Table Header** hides the column header row.
* **Hide Checkbox Column** removes the selection checkboxes, disabling row selection.
* **Show Row Number Column** displays a leading column that numbers the rows.
* **Row Number Offset** sets the number the row count starts from (default `0`). Requires **Show Row Number Column** to be enabled, and is hidden until it is.
* **Show Number of Items Selected** displays a running count of the selected rows.

### Header

* **Title** sets the heading shown above the grid, and **Caption** sets a smaller line displayed above the title.
* **Avatar** adds an avatar next to the title. Provide an **Image**, or **Initials** and a **Fallback Icon Name** used when the image is unavailable. **Alternative Text**, **Size** and **Variant** sit under **Advanced Options**.
* **Is Joined** squares off the header's bottom border so it sits flush on the component below it.
* **Actions** define the buttons shown in the header. **Visible Actions Buttons** sets how many appear inline before the rest collapse into an overflow menu.
* **Hide Actions** and **Disable Actions** hide or disable every header action at once.

### Row Toggle Icon

* **Open Icon Name** is shown when a row is expanded (default `utility:chevrondown`).
* **Close Icon Name** is shown when a row is collapsed (default `utility:chevronright`).

### Column Widths

* **Column Widths Mode** controls how column widths are calculated: **Fixed** (default) or **Auto**.
* **Max Column Width** (default `1000`) and **Min Column Width** (default `50`) bound each column's width in pixels.
* **Resize Column Disabled** prevents users from dragging column borders to resize.

### Pagination

* **Number of Additional Rows** sets how many more rows load at a time as the user scrolls to the end of the grid (1 to 200, default `100`).

### Sort

* **Default Sort Direction** sets the direction applied the first time a user sorts an unsorted column: **Ascending order** (default) or **Descending order**.
* Which columns users can sort is set per column, with the **Sortable** property in **Data Mappings**.

### No Results Message

* **No Results Message** replaces the default text shown when the grid has no rows to display.
* **Hide No Results Image** and **Hide No Results Message** suppress the image and the text.

***

## Interactions

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

Both interactions are scoped with a **Target Name**: you pick the specific action the interaction responds to, so each action can run its own logic without any branching on your side.

The actions an interaction can run depend on the data source. With **Query**, both interactions also offer **Delete Selected Record(s)**, **Duplicate Selected Record(s)**, **Edit Selected Record(s)** and **Refresh Query**. With **Manual** those four are absent, because manually entered rows have no Salesforce record behind them.

### Header Action Click

Fires when a user clicks a header action button. Set **Target Name** to the header action you want to react to.

### Row Action Click

Fires when a user clicks an action in a row's action menu. Set **Target Name** to the row action you want to react to, then use the **Clicked Row Action Row** output to act on the corresponding record.

***

## Output Variables

The Tree Grid exposes these output variables you can reference in your flow after the screen. To use them, select the screen element in Flow Builder, then the Tree Grid component, and pick the output variable you need.

### Row Selection

When a user selects one or more rows, these variables update with the current selection. Users select rows with the checkbox column, so they stay empty when **Hide Checkbox Column** is on.

| Output variable                                        | Type                           | What it returns                                                                                                                          |
| ------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Selected Rows**                                      | Record Collection (SObject\[]) | The full Salesforce records for every selected row.                                                                                      |
| **Selected Rows Key Field Value**                      | Text Collection                | The key-field value of every selected row.                                                                                               |
| **Selected Rows Key Field Value comma separated**      | Text (String)                  | The same values in one string, each wrapped in single quotes and separated by commas (`'a','b'`), ready to drop into a SOQL `IN` clause. |
| **Selected Rows Key Field Value semi colon separated** | Text (String)                  | The same values in one string, unquoted and separated by semicolons (`a;b`).                                                             |
| **Selected Rows Serialized**                           | Text (String)                  | The selected rows as a JSON string.                                                                                                      |

> **Example:** Let users tick several rows, then pass **Selected Rows** to a Delete Records element after the screen to remove them all in one step.

### Row Actions

When a user clicks an action in a row's action menu, these variables capture which action was clicked and on which row.

| Output variable                        | Type             | What it returns                                                  |
| -------------------------------------- | ---------------- | ---------------------------------------------------------------- |
| **Clicked Row Action Name**            | Text (String)    | The name of the row action the user clicked.                     |
| **Clicked Row Action Key Field Value** | Text (String)    | The key-field value of the row whose action was clicked.         |
| **Clicked Row Action Row**             | Record (SObject) | The full Salesforce record for the row whose action was clicked. |

> **Example:** After a "View details" row action, use **Clicked Row Action Row** on the next screen to show that record's fields.

### Header Actions

| Output variable                | Type          | What it returns                                        |
| ------------------------------ | ------------- | ------------------------------------------------------ |
| **Clicked Header Action Name** | Text (String) | The name of the header action button the user clicked. |

### Flow Interaction Output Variables

Like all interactive Flow components, the Tree Grid exposes generic output slots (Variable 1 to 10) that an [Open Flow Dialog](/flow/component-builder/interactions-panel/open-flow-dialog.md) or [Open Flow Panel](/flow/component-builder/interactions-panel/open-flow-panel.md) interaction can fill with values from a launched flow. See [Flow Interaction Output Variables](/flow/component-builder/interactions-panel/flow-interaction-output-variables.md).

***

## Styling

Configure the Tree Grid's appearance from the **Style** tab of the Edit Tree Grid Component panel.

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

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

{% tab title="Padding" %}
Controls the *inner* spacing between the component's content and its border.

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

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

* **Width / Height:** Set fixed dimensions.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the component.

* **Color / Size / Style / Radius:** Set the border color, thickness, style, and corner rounding.
  {% endtab %}

{% tab title="Header" %}
Styles the band that holds the title, caption, and avatar. The panel splits it into six groups.

* **Header:** Background Color, Padding Top / Right / Bottom / Left, and Margin Bottom, the space between the header and the grid.
* **Header Border:** Color, Size, Style, and Radius, plus a separate bottom border color, size and style that apply when **Is Joined** is on.
* **Header Title** and **Header Caption:** Color, Font Size, Font Style, and Font Weight for each.
* **Header Actions:** text, background and border colors, each with its own active and hover value.
* **Header Avatar:** Background Color, Foreground Color, and Border Radius.
  {% endtab %}

{% tab title="Flow Panel" %}
Appears only once the component has an **Open Flow Panel** interaction, and styles the panel that interaction opens. Two groups.

* **Flow Panel:** Background Color, Border Color, Border Size, Border Style, and Border Radius.
* **Flow Panel Header:** Background, bottom border color and size, the label's Color, Font Size and Font Weight, and the close icon's color in its normal and its active state.
  {% endtab %}
  {% endtabs %}

***

## Troubleshooting

* **Rows don't expand.** With the **Manual** source, child rows are created from a row's action menu with **Add**, not by adding separate top-level rows, and **Key Field** must point at a column whose values are unique. With the **Query** source, check that every entry under **Items** names the relationship field tying its object back to the level above.
* **Columns are truncated.** Switch **Column Widths Mode** to **Auto**, raise **Max Column Width**, or turn on **Wrap Text** for the column in **Data Mappings**.
* **Values show as plain text.** Column types are only available with the **Query** data source. Manual rows always render as text.
* **No data appears.** Verify the Manual rows or the Query return records, and check **No Results Message** to confirm what the empty state should say.


---

# 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/flow/flow-components/tree-grid.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.