> 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/avatar-group.md).

# Avatar Group

The Avonni Avatar Group component displays a collection of avatars — people, users, or related records — in a compact, visually engaging group. Use it to represent teams, project members, or any list of individuals directly on your Experience page.

## Overview

The Avatar Group supports three builder presets that correspond to its three layout modes: **Avatar Stack** (overlapping avatars), **Avatar Grid** (tiled layout), and **Avatar List** (horizontal list with labels). All three are the same underlying component. Each preset sets the initial **Layout** value, and also sets **Variant** to Circle and drops in three placeholder avatars so you can see the shape before wiring up your data. Change any of it afterwards: dragging in a preset commits you to nothing.

Connect the component to a Salesforce object to generate avatars dynamically, or build a fixed set of avatars manually. You can optionally add a header, enable filtering, and allow users to search through large groups.

**Use cases**

* **Team rosters:** Display the members of a team or department.
* **Project teams:** Show avatars for everyone working on a project.
* **Customer lists:** Represent the contacts or users associated with an account.

## Configuration

To configure the Avatar Group, select it on the canvas. The **Edit Avatar Group** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FQFPcwYvZdPCfYTEPX8og%2Favatar-group-builder-properties.png?alt=media" alt="The Properties tab of the Edit Avatar Group panel" width="320"><figcaption><p>The Data Source switch, the Items collection, then the settings that follow it with no group heading of their own.</p></figcaption></figure>

### Data Source

Before the Avatar Group can display anything, you must tell it where to get its data. You have three options:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Manual</strong></td><td>Enter data directly into the component configuration.</td><td></td></tr><tr><td><strong>Variable</strong></td><td>This is useful for data that changes based on user interactions or other component logic.</td><td></td></tr><tr><td><strong>Query</strong></td><td>This is the most common option for displaying Salesforce records.</td><td></td></tr></tbody></table>

### Data Mapping

When using a dynamic data source (Query or Variable), configure the **Data Mappings** section to tell the component how to build each avatar from your records.

Map fields from your Salesforce object to avatar attributes. The full set is:

| Group        | Attributes                                                                                            |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| **Identity** | Initials, Image Source, Fallback Icon Name                                                            |
| **Text**     | Primary Text, Secondary Text, Tertiary Text, Tooltip                                                  |
| **Link**     | URL, Target                                                                                           |
| **Badges**   | Tags, Status Type, Status Position, Status Title, Presence Type, Presence Position, Presence Title    |
| **Entity**   | Entity Icon Name, Entity Initials, Entity Image Source, Entity Variant, Entity Position, Entity Title |

Each avatar in the group therefore carries the same surface as a standalone [Avatar](/dynamic-components/components/avatar.md): a status dot, a presence dot, an entity badge and tags are all set per record, not just the name and the photo. The same set is available field by field when the data source is **Manual**.

**Key Field**

Also in the Data Mappings section, **Key Field** holds the unique identifier of each avatar and defaults to `{{Record.Id}}`. It is the value returned as the name of the **Clicked Item** output variable, so set it to something you can branch on if you plan to use that output.

**Filters**

The **Filters** field selects which mapped fields are available to end-users as filters. Only the fields you select here appear in the filter menu.

**Search Fields**

By default, the search covers all searchable fields you map in the Data Mappings section. Use **Search Fields** to limit the search to specific mapped fields.

### Core Settings

The Properties tab lists these settings directly under **Data Source**, with no group heading above them. They control the core appearance and behaviour of the avatar group.

#### Variant

Sets the shape of all avatars in the group. Choose **Circle** for round avatars or **Square** for square ones. The property itself defaults to Square, but all three builder presets set it to Circle, so a component dragged in from the palette starts round.

#### Size

Controls how large each avatar is rendered. Options range from **X-Small** to **Xx-Large**, with **Medium** as the default. Larger sizes such as X-Large and Xx-Large also reveal tertiary text details on each avatar.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2Foo5HtUlzLi7v26Tx0HM1%2Favatar-group-size.png?alt=media" alt="The six sizes of the Avatar Group in the List layout"><figcaption><p>The six values of <strong>Size</strong>. Tertiary text appears only at X-Large and Xx-Large.</p></figcaption></figure>

#### Icon Position

When an avatar displays a fallback icon (no image or initials), this setting controls where the icon is placed within the avatar frame: **Start**, **Center** (default), or **End**.

#### Layout

Determines how avatars are arranged:

* **Stack** (default) — avatars overlap slightly, creating a compact clustered look.
* **Grid** — avatars are arranged in a tile grid.
* **List** — avatars appear in a horizontal row with full label details visible.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F9ccFKHjTHGnDwBIomM7z%2Favatar-group-layout.png?alt=media" alt="The Avatar Group in its stack, grid and list layouts"><figcaption><p>The three values of <strong>Layout</strong>, over the same four avatars.</p></figcaption></figure>

#### Max Count

The maximum number of avatars displayed at once (1–500). Use this to keep the group tidy when the data source returns many records.

#### Initials Auto Formatted

When enabled, the component automatically derives two-letter initials from each avatar's name: first letters of each word for multi-word names, or the first two letters for a single word.

#### Items Clickable

When enabled, every avatar in the group becomes clickable. Configure what happens on click in the **Interactions** tab.

### Header

The **Header** group lets you add context above the avatar group.

| Setting             | Description                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**           | Main heading displayed in the header.                                                                                                                                                                                                                                                                                                                                                    |
| **Caption**         | Supplementary text shown above the title.                                                                                                                                                                                                                                                                                                                                                |
| **Avatar**          | An optional avatar in the header. Set an **Image**, **Fallback Icon Name**, or **Initials**; adjust **Size**, **Variant**, and **Alternative Text** under Advanced Options.                                                                                                                                                                                                              |
| **Help Text**       | A hoverable icon in the header that reveals guidance text for users.                                                                                                                                                                                                                                                                                                                     |
| **Is Joined**       | Removes the rounded shadow at the bottom of the header so it sits flush against the component below.                                                                                                                                                                                                                                                                                     |
| **Actions**         | Buttons added to the header that trigger interactions. Each action carries a **Label**, a **Name** (the value returned by the **Clicked Header Action Name** output), an optional **Icon Name**, and the **Disabled**, **Hidden**, **Title** and **Alternative Text** options. Use **Visible Actions Buttons** to control how many appear directly before the rest overflow into a menu. |
| **Hide Actions**    | Hides the header actions menu. Defaults to off.                                                                                                                                                                                                                                                                                                                                          |
| **Disable Actions** | Disables the header actions menu so users cannot interact with it. Defaults to off.                                                                                                                                                                                                                                                                                                      |

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F3E3GspDmY3sFcvmO4iPI%2Favatar-group-header.png?alt=media" alt="The Avatar Group header with caption, title, avatar, help icon and actions"><figcaption><p>A header carrying every one of its parts: caption, title, avatar, help icon, and two visible actions before the overflow menu.</p></figcaption></figure>

### Filter

The **Filter** group controls how the filter menu is presented to end-users. Filter fields are enabled in the Data Mappings section.

* **Display As Popover** — when enabled, the filter controls appear in a floating popover instead of inline.
* **Use Record Picklist Values** — when filtering a picklist field, derives the filter options only from values actually present in the loaded records rather than the field's full picklist definition.
* **Use Cascading Filter Values** — when enabled, selecting a filter option narrows the choices available in all other filters to only those matching the current selection. Overrides **Use Record Picklist Values**.

### Search

The **Search** group adds a search bar so users can find specific avatars by name or other fields.

* **Show Search** — toggle to enable the search bar.
* **Placeholder** — the hint text shown inside the search input before the user types. Defaults to `Search`. Requires **Show Search** to be enabled.
* **Position** — where the search bar appears: **Left** (default), **Right**, **Center**, or **Fill** (stretches to available width). Requires **Show Search** to be enabled.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FTlN6Maamn5xIXhfOgEuS%2Favatar-group-search.png?alt=media" alt="The Avatar Group search bar at the Left and Fill positions"><figcaption><p>The search bar at <strong>Left</strong> and at <strong>Fill</strong>.</p></figcaption></figure>

### 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 Avatar Group. Configure them from the **Interactions** tab of the Edit Avatar Group panel.

### Avatar Click

Fires when a user clicks an avatar. Requires **Items Clickable** to be enabled. Use this to navigate to a record page, open an edit form, or trigger any flow logic tied to the selected avatar.

### Header Action Click

Fires when a user clicks one of the header action buttons. Use the **targetName** output to identify which action was clicked and branch your flow logic accordingly.

## Output Variables

The Avatar Group exposes these output variables you can reference elsewhere on the page after the user interacts with it.

### Avatar Click

When a user clicks an avatar, these variables update with the clicked avatar's data.

| Output variable          | Type             | What it returns                                                                                                                             |
| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Clicked Item**         | Object           | The clicked avatar's data — its name, primary text, secondary text, tertiary text, initials, image source, fallback icon, href, and target. |
| **Clicked Item sObject** | Record (SObject) | The full Salesforce record associated with the clicked avatar. Requires a **Query** or **Variable** data source.                            |

> **Example:** When a user clicks a team member's avatar, use **Clicked Item sObject** to display that person's Contact record details in a side panel.

### Header Actions

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

> **Example:** Use **Clicked Header Action Name** to branch logic — navigate to a "New Contact" form when the value is `new`, or open a report when it is `view-all`.

### Others

| Output variable     | Type   | What it returns                                            |
| ------------------- | ------ | ---------------------------------------------------------- |
| **Number of Items** | Number | The total number of avatars currently loaded in the group. |

## Styling

Configure the Avatar Group's appearance from the **Style** tab of the Edit Avatar Group panel.

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

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

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

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

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

* **Color:** Set the border color.
* **Size:** Set the border thickness.
* **Style:** Set the border style (solid, dashed, dotted, etc.).
* **Radius:** Round the corners of the border.
  {% endtab %}

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

* **Width / Height:** Set fixed dimensions for the group.
* **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds.
* **Overflow:** Control how content that exceeds the bounds is handled.
  {% endtab %}

{% tab title="Header" %}
Styles the header background and spacing.

* **Background Color:** Set the header background color.
* **Padding Top / Right / Bottom / Left:** Adjust the inner spacing of the header.
* **Margin Bottom:** Set the space below the header.
  {% endtab %}

{% tab title="Stack Border" %}
Customizes the border drawn around each avatar in the **Stack** layout.

* **Color:** Set the border color.
* **Size:** Set the border thickness.
* **Style:** Set the border style (solid, dashed, dotted, etc.).
  {% endtab %}

{% tab title="Show More Button" %}
Customizes the button that reveals avatars beyond the **Max Count**.

* **Background Color / Text Color / Border Color:** Set the colors for the default, active, and hover states.
* **Border Size / Border Radius:** Control the button border.
* **Block Start / Block End / Inline Start / Inline End:** Set the spacing around the button.
  {% 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/avatar-group.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.