Relationship Graph

avonni-dd-relationship-graph

The Avonni Data Driven Relationship Graph displays related records as nested graph items.

Overview

Relationship Graph is a data-driven Lightning Web Component that displays related records as nested, expandable graph items.

You describe the record hierarchy with a nested query — a root object with children levels linked by their relationship fields — and a mapping that, per SObject, turns each record's fields into a graph item's label and name. Groups can expand and collapse, and root, group, and item actions surface as clickable menus that fire the actionclick, groupactionclick, and itemactionclick events.

Use Cases

• Account hierarchies: Show an account with its contacts and related events.
• Org charts: Render reporting or ownership relationships.
• Case context: Display a case alongside its related records.
• Record exploration: Let users expand branches to drill into related data.
• Actionable graphs: Attach actions to the root, groups, or individual items.

---

Use Case Examples

Example 1: Account with contacts and events

Scenario: Show accounts, their contacts, and each contact's events as a horizontal graph.

<!-- accountGraph.html -->
<template>
    <avonni-dd-relationship-graph
        label="Account Relationships"
        query={graphQuery}
        mapping={graphMapping}
        variant="horizontal"
        onactionclick={handleActionClick}
    ></avonni-dd-relationship-graph>
</template>

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

export default class AccountGraph extends LightningElement {
    graphQuery = {
        objectApiName: 'Account',
        orderBy: 'Name ASC NULLS LAST',
        children: [
            {
                objectApiName: 'Contact',
                relationshipField: 'AccountId',
                orderBy: 'Name ASC',
                limit: 5,
                children: [
                    {
                        objectApiName: 'Event',
                        relationshipField: 'WhoId',
                        orderBy: 'Subject ASC NULLS LAST'
                    }
                ]
            }
        ]
    };

    // Each key is an SObject API name; {{Record.FieldApiName}} inserts a field value.
    graphMapping = {
        Account: { label: '{{Record.Name}}', name: '{{Record.Id}}', fields: ['Industry'] },
        Contact: { label: '{{Record.Name}}', name: '{{Record.Id}}' },
        Event: { label: '{{Record.Subject}}', name: '{{Record.Id}}' }
    };

    handleActionClick(event) {
        const { name, targetName } = event.detail;
    }
}

Result: A horizontal graph of accounts, each expandable to its contacts and their events.

Example 2: Vertical graph with item actions

Scenario: Render the same data vertically with an action on each item.

<!-- verticalGraph.html -->
<template>
    <avonni-dd-relationship-graph
        label="Relationships"
        query={graphQuery}
        mapping={graphMapping}
        variant="vertical"
        item-actions={itemActions}
        onitemactionclick={handleItemActionClick}
    ></avonni-dd-relationship-graph>
</template>

Result: A vertical graph where each item exposes an action menu that fires itemactionclick.

Specifications

Attributes

Name	Description	Type	Default	Required
actions	Array of actions to display at the root of the graph. On click on a root action, the actionclick event is fired.	DdElementAction[]	—
avatar-attributes	Object defining how the avatar displayed at the root of the graph.	DdRelationshipGraphAvatarAttributes	—
expand-icon-name	Icon used to expand a closed group of items.	String	"utility:chevronright"
group-actions	Array of actions to display at the top right of the group header. On click on a group action, the groupactionclick event is fired.	DdRelationshipGraphAction[]	—
group-actions-position	The position of the group actions. Valid values are top and bottom.	String	"top"
hide-items-count	If true, the items count is hidden.	Boolean	false
href	URL for the root label link.	String	—
item-actions	Array of actions to display at the top right of the item header. On click on an item action, the itemactionclick event is fired.	DdRelationshipGraphItemAction[]	—
label	The text that's displayed as the relationship graph root label.	String	—
mapping	Object defining the way the records returned by the query should be displayed in the relationship graph. 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 graph 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, DdRelationshipGraphMapping>	—
selected-item-name	Name of the selected item.	String	—
shrink-icon-name	Icon used to shrink an expanded group of items.	String	"utility:chevrondown"
target	Target attribute for the link.	String	—
variant	The variant changes the appearance of the graph. Valid values include horizontal and vertical.	String	"horizontal"

Custom Events

actionclick

The event fired when a root action is clicked.

The actionclick 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.

groupactionclick

Event fired when a group action is clicked.

The groupactionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.
targetName	string	Name of the group the action is related to.

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.

itemactionclick

Event fired when an item action is clicked.

The itemactionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.
targetName	string	Name of the item the action is related to.

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
record	object	Record of the item that was selected or unselected.

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-relationship-graph-line-color	color	—
--avonni-dd-relationship-graph-selected-line-color	color	—
--avonni-dd-relationship-graph-children-indicator-color	color	—