> 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-grid.md). # Tree Grid The Avonni Tree Grid component displays hierarchical tabular data in an expandable tree grid. It combines the columns of a data table with a nested, collapsible row structure, which makes it a good fit for parent/child records, roll-ups, and any data with a natural hierarchy. ## Overview Each row can contain child rows that users expand and collapse from a toggle in the first column. The grid supports column formatting, row selection, header actions, per-row actions, sorting, resizable columns, and loading additional rows on demand. Drive it from a Salesforce query or from data you enter by hand.

A Tree Grid with three levels expanded, showing the open and closed toggle icons — A territory hierarchy expanded from region to account. The toggle in the first column shows its open icon on expanded rows and its closed icon on the rest.

**Common use cases** * Show Accounts with their child Accounts or related Contacts nested beneath them. * Display a category, sub-category, item hierarchy in a single grid. * Present roll-up structures (territories, org charts, product bundles) with expandable detail. ## Configuration To configure the Tree Grid, select it on the canvas. The **Edit Tree Grid** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.

The Component Builder with a Tree Grid selected on the canvas and its Edit panel open — Selecting the Tree Grid on the canvas opens the Edit Tree Grid panel on the right.

### Data Source Before you build your tree grid, you must tell the component where to get the data it should display. You have two options:


Manual	Enter rows directly into the component configuration, nesting child rows under their parent. Best for small, fixed hierarchies.	/pages/p2RQTJ1oud3ALc4E5ott
Query	Fetch records from Salesforce using a nested query, so child records load beneath their parent. The most common option for live data.	/pages/nLmnEEgTMr9Ezh8Xhe92

Your choice changes the rest of the Properties tab: **Manual** shows the **Data** section described below, **Query** shows the **Data Mappings** section instead. #### Manual data Configure the three properties in this order, because each one depends on the previous. 1. **Columns**: add one entry per column you want to display. Each entry has a **Label** (the text shown in the column header) and a **Name** (the key that binds the column to your data). 2. **Key Field**: select which column uniquely identifies a row. This is required, and the **Data** property stays locked until you set it. 3. **Data**: enter your rows. The editor shows one field per column you defined.

The Properties tab showing the Manual and Query switch, then Columns, Key Field and Data — The Properties tab, with the three manual properties in the order you fill them.

To build the hierarchy, open a row's action menu and choose **Add**. The new row is created as a child of the row you started from, and you can nest as many levels as you need. The same menu offers **Edit**, **Move Up**, **Move Down**, and **Delete**. {% hint style="warning" %} Manual columns have no data 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 configure the types in **Data Mappings**. {% endhint %} #### Query data The Query data source must be structured as a **nested query**, even when you only display one level of records. The top level supplies the root rows, and each child query supplies the rows nested beneath them (for example, Account, then Opportunity, then Contact). For each level, map the row **Name** (usually the record Id) and the row **Label** (usually Name or Subject). Columns are configured separately, in **Data Mappings**. ### Data Mappings The **Data Mappings** section appears when you use 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 (a button or an action menu, for example). * **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**: the column's unique key. It fills in automatically from the **Label**, has to be unique among the columns, and cannot contain special characters. * **Data Type**: controls how the value is formatted (Text, Number, Currency, Date, Badge, Avatar, Progress Bar, Action, and more). The type 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.

One Tree Grid column per data type: text, text with a cell icon, currency, date, progress bar and badge — What the data types render as, left to right: Text, Text with a cell icon, Currency, Date, Progress Bar, and Badge.

{% hint style="info" %} Row actions are configured as a column: add a column, set its **Data Type** to **Action**, and define the actions in its type attributes. Those actions are what the **Row Action Click** interaction responds to. {% endhint %} ### Content **Hide Table Header** removes 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. **Show Number of Items Selected** displays a running count of the currently selected rows.

A Tree Grid with row numbers, selection checkboxes and a selected count above the table — Row numbers, selection checkboxes, and the running count of 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 no image is available. **Help text** adds an information icon beside the title, with the **Content** you enter shown on hover or focus. **Is Joined** squares off the header's bottom border and removes its shadow, so the header 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 all header actions at once.

A header with every part in place, and Visible Actions Buttons set to 2, so the third action falls into the overflow menu.

### Row Toggle Icon Sets the two icons used on the expand and collapse toggle in the first column. **Open Icon Name** is shown when a row is expanded (default `utility:chevrondown`), and **Close Icon Name** is shown when it is collapsed (default `utility:chevronright`).

The default chevron pair on the left, and a custom utility:dash and utility:add pair on the right.

### 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. ### 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. ### Pagination **Number of Additional Rows** sets how many more rows load at a time when the user reaches the end of the grid. The default is `100`, and the value must be between `1` and `500`. ### Set Component Visibility All components support conditional visibility, see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md). ## Interactions [Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Tree Grid. Configure them from the **Interactions** tab of the Edit Tree Grid panel. Both interactions below 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. ### 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 sObject** output to act on the corresponding record. ## Output Variables The Tree Grid exposes these output variables you can reference elsewhere on the page after the user interacts with it. ### Row Selection When a user selects one or more rows, these variables update with the current selection. | Output variable | Type | What it returns | | ------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------ | | **Selected Rows sObject** | Record Collection (SObject\[]) | The full Salesforce records for all selected rows. Requires a **Query** data source. | | **Selected Rows Key Value** | Text Collection | The key-field values (record IDs, typically) for all selected rows. | | **Selected Rows Key Value (Comma Separated)** | Text (String) | The selected rows' key-field values joined into a single comma-separated string. | | **Selected Rows Key Value (Semicolon Separated)** | Text (String) | The selected rows' key-field values joined into a single semicolon-separated string. | > **Example:** When a user selects several rows, pass **Selected Rows sObject** to a Delete Records action to remove them all in one step. ### Row Action Click When a user clicks an action in a row's action menu, these variables update with the clicked row's data. | Output variable | Type | What it returns | | ------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------ | | **Clicked Row Action Name** | Text (String) | The name of the row action the user clicked. | | **Clicked Row Action - Row** | Object | The row where the action was clicked, as an object (column name to cell value). | | **Clicked Row Action - Row sObject** | Record (SObject) | The full Salesforce record for the row where the action was clicked. Requires a **Query** data source. | > **Example:** When the user clicks a "View" row action, use **Clicked Row Action - Row sObject** in a Navigate interaction to open that record. ### Header Actions | Output variable | Type | What it returns | | ------------------------------ | ------------- | ------------------------------------------------------ | | **Clicked Header Action Name** | Text (String) | The name of the header action button the user clicked. | ### Others | Output variable | Type | What it returns | | ------------------- | ------ | ------------------------------------------------------------- | | **Number of Items** | Number | The total number of items in the tree grid at the root level. | ## Styling Configure the Tree Grid's appearance from the **Style** tab of the Edit Tree Grid 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. * **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds. {% 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 grid header, its border, title, caption, and avatar. * **Header:** Background color, padding, and bottom margin. * **Header Border:** Color, size, style, radius, and the joined-state bottom border. * **Header Title:** Color, font size, font style, and font weight. * **Header Caption:** Color, font size, font style, and font weight. {% endtab %} {% endtabs %} --- # 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-grid.md?ask=&goal= ``` `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.