Tree

avonni-dd-tree

The Avonni Data Driven Tree displays related records as nested tree items.

Overview

Tree is a data-driven Lightning Web Component that displays related records as nested, expandable tree items, with each level of the hierarchy populated by its own query.

The Tree runs in query mode only. You define a query whose children describe each nested level and the lookup field that relates it to its parent, plus a per-object mapping that maps record fields to tree item properties. The component fetches every level and renders the resulting hierarchy. There is no static-items mode.

Use Cases

• Account hierarchies: Show Accounts with their related Contacts and Opportunities nested beneath.
• Org and team structures: Represent reporting or grouping relationships across objects.
• Record navigation: Let users drill from a parent record into related children in a single tree.
• Multi-object browsing: Combine several SObjects into one nested view (e.g. Account → Contact → Event).
• Selection pickers: Use single- or multi-select to choose records from a related hierarchy.

---

Use Case Examples

Example 1: Query mode

Scenario: Display Accounts with their related Contacts nested beneath each account, showing how many contacts each account has.

<!-- accountTree.html -->
<template>
    <avonni-dd-tree
        query={treeQuery}
        mapping={treeMapping}
        show-item-count
        onselect={handleSelect}
    ></avonni-dd-tree>
</template>

// accountTree.js
import { LightningElement } from 'lwc';

export default class AccountTree extends LightningElement {
    treeQuery = {
        objectApiName: 'Account',
        orderBy: 'Name ASC NULLS LAST',
        limit: 50,
        children: [
            {
                objectApiName: 'Contact',
                relationshipField: 'AccountId',
                orderBy: 'Name ASC',
                limit: 10
            }
        ]
    };
    treeMapping = {
        Account: {
            label: '{{Record.Name}}',
            name: '{{Record.Id}}',
            metatext: '{{Record.Industry}}'
        },
        Contact: {
            label: '{{Record.Name}}',
            name: '{{Record.Id}}',
            metatext: '{{Record.Title}}'
        }
    };

    handleSelect(event) {
        const { record, selectedNames } = event.detail;
    }
}

Result: A tree of Accounts (each showing its Industry as metatext) with a child count badge. Expanding an account reveals up to 10 related Contacts, each showing its Title. Clicking an item fires select with the clicked record and the current selection.

Example 2: Multi-level, multi-select query

Scenario: Build a three-level hierarchy—Account → Contact → Event—and let users select multiple records at once.

<!-- relatedTree.html -->
<template>
    <avonni-dd-tree
        query={treeQuery}
        mapping={treeMapping}
        is-multi-select
        independent-multi-select
        show-item-count
        onselect={handleSelect}
    ></avonni-dd-tree>
</template>

// relatedTree.js
import { LightningElement } from 'lwc';

export default class RelatedTree extends LightningElement {
    treeQuery = {
        objectApiName: 'Account',
        orderBy: 'Name ASC',
        limit: 25,
        children: [
            {
                objectApiName: 'Contact',
                relationshipField: 'AccountId',
                orderBy: 'Name ASC',
                limit: 5,
                children: [
                    {
                        objectApiName: 'Event',
                        relationshipField: 'WhoId',
                        orderBy: 'Subject ASC NULLS LAST'
                    }
                ]
            }
        ]
    };
    treeMapping = {
        Account: { label: '{{Record.Name}}', name: '{{Record.Id}}' },
        Contact: {
            label: '{{Record.Name}}',
            name: '{{Record.Id}}',
            metatext: '{{Record.Title}}'
        },
        Event: { label: '{{Record.Subject}}', name: '{{Record.Id}}' }
    };

    handleSelect(event) {
        const { record, selectedNames } = event.detail;
        // selectedNames holds every checked item across all levels
    }
}

Result: A three-level tree where each Account expands into Contacts, and each Contact expands into its related Events. Checkboxes let users select records; because independent-multi-select is set, selecting a parent does not auto-select its children. Each select event reports the full set of checked item names.

---

Specifications

Attributes

Name	Description	Type	Default	Required
filters	Array of field API names that belong to the queried object. These fields will be displayed as user filters.	string[]	—
filters-attributes	Object defining the filters-specific attributes.	DdElementFiltersAttributes	—
header-actions	Array of actions to display at the top right of the header. On click on a header action, the headeractionclick event is fired.	DdElementAction[]	—
header-avatar	Avatar displayed at the top left of the header.	DdElementAvatar	—
header-help-text	If present, a help text icon is displayed next to the header title. On focus or hover on the icon, the header help text is displayed in a tooltip.	String	—
header-help-text-attributes	Object defining the help text-specific attributes.	DdElementHelpTextAttributes	—
header-title	Main title displayed in the header.	String	—
header-visible-actions-count	Number of header actions that appear as regular buttons. Remaining actions appear in a dropdown menu.	integer	—
independent-multi-select	Used only if is-multi-select is present. If present, the parent and children nodes will be selected independently of each other.	Boolean	false
is-multi-select	If present, multiple items can be selected and a checkbox is displayed to the left of the items.	Boolean	false
items	Array of static items displayed in the tree. When this property is set, the tree ignores the query and mapping properties and displays the items directly.	DdTreeItem[]	—
mapping	Object defining the way the records returned by the query should be displayed in the tree. Each key is an SObject API name (e.g., 'Account', 'Contact'), and each value is an object that defines how the records fields should be mapped to the tree item properties. To insert the value of a field, use the syntax {{Record.FieldApiName}}. For example, to use the value of the Name field, use {{Record.Name}}.	object.<string, DdTreeMapping>	—
query	Object describing the queries that should be executed to fetch the records on each level of the relationship graph.	DdNestedQueryElementQuery	—
refresh-emp	Object describing a platform event that should be subscribed to in order to refresh the component when an event is published.	DdElementRefreshEmp	—
search-attributes	Object defining the search-specific attributes.	DdElementSearchAttributes	—
search-fields	Array of field API names that can be used by the search box to filter the records. The fields must belong to the queried object, and they must be filterable.	string[]	—
show-item-count	If present, the number of children items is displayed next to each item label.	Boolean	false
side-panel-attributes	Object defining the side panel-specific attributes.	DdElementSidePanelAttributes	—

Methods

Name	Description	Argument Name	Argument Type	Argument Description
refresh	Refresh the query and the records displayed in the component.

Mapping

The Tree's mapping is keyed by SObject API name. Each entry maps that object's record fields to tree item properties using the {{Record.FieldApiName}} syntax.

Mapping key	Maps to
label	Item label (the text shown for the node).
name	Unique item identifier (usually {{Record.Id}}). Required.
metatext	Secondary text displayed below the item label.
disabled	If true, the item is disabled and cannot be selected or toggled.

const TREE_MAPPING = {
    Account: {
        label: '{{Record.Name}}',
        name: '{{Record.Id}}',
        metatext: '{{Record.Industry}}'
    },
    Contact: {
        label: '{{Record.Name}}',
        name: '{{Record.Id}}',
        metatext: '{{Record.Title}}'
    }
};

Within query, each children entry must specify a relationshipField—the lookup field on the child SObject that points back to the parent level (for example, AccountId on Contact relating it to Account).

Custom Events

error

The event fired when an error occurs in the component.

The error event returns the following parameters.

Parameter	Type	Description
message	string	Message of the error.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

filter

The event fired when the user filters the records.

The filter event returns the following parameters.

Parameter	Type	Description
value	object	Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

headeractionclick

The event fired when a header action is clicked.

The headeractionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

nbitemschange

The event fired when the number of items displayed in the component changes.

The nbitemschange event returns the following parameters.

Parameter	Type	Description
value	integer	Number of items displayed in the component.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

select

Event fired when an item is selected or unselected.

The select event returns the following parameters.

Parameter	Type	Description
item	object	Tree item that was selected or unselected.
record	object	Record of the item that was selected or unselected. In static mode, no record is associated and this is null.
selectedNames	string[]	Array of selected item names.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

select

Event fired when an item is selected or unselected.

The select event returns the following parameters.

Parameter	Type	Description
item	object	Tree item that was selected or unselected.
record	object	Record of the item that was selected or unselected. In static mode, no record is associated and this is null.
selectedNames	string[]	Array of selected item names.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-dd-tree-header-font-size	dimension	0.875rem
--avonni-dd-tree-header-font-style	string	normal
--avonni-dd-tree-header-font-weight	number	700
--avonni-dd-tree-header-text-color	color	—
--avonni-dd-tree-header-title-image-height	dimension	3rem
--avonni-dd-tree-header-title-image-object-fit	string	cover
--avonni-dd-tree-header-title-image-width	string	unset

Key Considerations

• Query mode only: The Tree has no static-items mode; you must supply a query and a mapping to render anything.
• Mapping is keyed by object: Every SObject appearing in the query (parent and each child) needs its own entry in mapping, keyed by API name.
• relationshipField is required for children: Each child query must name the lookup field that ties it to the parent level, or that level won't load.
• Selection mode matters: By default selection is single; add is-multi-select for checkboxes, and independent-multi-select to decouple parent/child selection.
• Mind the limits: Set limit and orderBy per level—deep hierarchies without limits can fetch large volumes of records.
• Best Practice: Map name to {{Record.Id}} on every object so each tree item has a unique, stable identifier, and set orderBy (and a sensible limit) on each query level to keep large hierarchies readable.

---

Troubleshooting Common Issues

• Children don't appear: Verify each child query has the correct relationshipField (the lookup on the child object pointing to the parent) and that the running user can access those records.
• Items render blank or without labels: Ensure every queried object has a mapping entry with label and a unique name (such as {{Record.Id}}).
• Selection behaves unexpectedly: Confirm is-multi-select is present for checkbox selection, and add independent-multi-select if parent and child selection should not cascade.
• If issues persist: Contact our support team at [email protected] for assistance.