> 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 — the preset simply sets the initial **Layout** value.
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.
### Data Source
Before the Avatar Group can display anything, you must tell it where to get its data. You have three options:
Manual
Enter data directly into the component configuration.
Variable
This is useful for data that changes based on user interactions or other component logic.
Query
This is the most common option for displaying Salesforce records.
### 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 such as:
* **Initials** — typically the first letters of a first and last name field.
* **Primary Text** — commonly the record name or a key identifier.
* **Secondary Text** — a role, title, or other supporting detail.
* **Image** — a URL field containing the avatar photo.
### Content
The Content group controls 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** (default) for square ones.
#### 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.
#### 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.
#### 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** and **Variant** 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. Use **Visible Actions Buttons** to control how many appear directly before the rest overflow into a menu. |
### Filter
The **Filter** group lets users narrow down the avatars shown.
* **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`.
* **Position** — where the search bar appears: **Left** (default), **Right**, **Center**, or **Fill** (stretches to available width). Requires **Show Search** to be enabled.
### 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. |
---
# 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=&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.