> 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/lwc-components/data-driven-components/relationship-graph.md).

# 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.

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

```js
// 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.

```html
<!-- 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 | —       |


---

# 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/lwc-components/data-driven-components/relationship-graph.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.