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

# Avatar Group

`avonni-avatar-group`

Displays a group of avatars, laid out in a stack or grid, with extra items collapsed into an overflow indicator.

## Overview

**Avatar Group** is a Lightning Web Component that displays a collection of avatars together as a stack, grid, or list, with overflow handling and per-avatar actions.

Use it in your own Lightning Web Components to represent teams, attendees, or collaborators. You control the layout, size, shape, overflow count, and the items array, and you can respond to clicks on avatars and their actions.

### Use Cases

* **Team rosters:** Show all members assigned to a project or record.
* **Attendee lists:** Display meeting or event participants compactly.
* **Collaborators:** Surface everyone sharing or editing a document.
* **Owner pools:** Represent a group of record owners with overflow.
* **Interactive directories:** Let users click avatars to open profiles or run actions.

***

## Layout Guidelines

| Layout  | Use Case                                           |
| ------- | -------------------------------------------------- |
| `stack` | Compact overlapping avatars for dense headers.     |
| `grid`  | Even, wrapping grid for larger member pools.       |
| `list`  | Vertical list with detail text and show more/less. |

***

## Use Case Examples

### Example 1: Stacked team avatars

**Scenario:** Show a compact stack of project members in a record header.

```html
<!-- projectTeam.html -->
<template>
    <avonni-avatar-group
        items={items}
        layout="stack"
        size="medium"
        variant="circle"
        max-count="5"
    ></avonni-avatar-group>
</template>
```

**Result:** Up to five overlapping circular avatars, with the rest collapsed into an overflow indicator.

### Example 2: Interactive member list

**Scenario:** Show members as a list with actions, and respond to clicks.

```html
<!-- memberList.html -->
<template>
    <avonni-avatar-group
        items={items}
        layout="list"
        max-count="4"
        size="large"
        variant="circle"
        layout-attributes={layoutAttributes}
        onitemclick={handleItemClick}
        onitemactionclick={handleItemActionClick}
        onitemsvisibilitytoggle={handleItemsVisibilityToggle}
    ></avonni-avatar-group>
</template>
```

```js
// memberList.js
import { LightningElement } from 'lwc';

export default class MemberList extends LightningElement {
    items = [
        {
            name: 'ava-thompson',
            initials: 'AT',
            fallbackIconName: 'standard:user',
            alternativeText: 'Ava Thompson',
            primaryText: 'Ava Thompson',
            secondaryText: 'Product Designer',
            actions: [{ label: 'View profile', name: 'view' }]
        }
        // ...more items
    ];
    layoutAttributes = {
        showMoreLabel: 'Show more members',
        showLessLabel: 'Show fewer members',
        showToggleVariant: 'brand'
    };

    handleItemClick(event) {
        const name = event.detail.name;
    }
    handleItemActionClick(event) {
        const { name, targetName } = event.detail;
    }
    handleItemsVisibilityToggle(event) {
        const showingMore = event.detail.show;
    }
}
```

**Result:** A list of avatars with detail text and a Show more/less button; clicks fire `itemclick`, `itemactionclick`, and `itemsvisibilitytoggle`.

***

## Specifications

### Attributes

| Name                                  | Description                                                                                                                                                                               | Type                              | Default                                         | Required |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------- | -------- |
| `icon-position`                       | The icon position of the avatars . Valid values are start, center, end.                                                                                                                   | String                            | `"center"`                                      |          |
| `items`                               | An array of items to be rendered as avatar in a group.                                                                                                                                    | AvonniAvatarGroupItem\[]          | —                                               |          |
| `keyboard-assistive-text`             | The assistive text used to describe the keyboard navigation.                                                                                                                              | String                            | `"Move between the items by using arrow keys."` |          |
| `layout`                              | Defines the layout of the avatar group. Valid values include stack, grid and list.                                                                                                        | String                            | `"stack"`                                       |          |
| `layout-attributes`                   | Attributes specific to certain layout values.                                                                                                                                             | AvonniAvatarGroupLayoutAttributes | —                                               |          |
| `list-button-show-less-icon-name`     | The Lightning Design System name of the list button icon. Specify the name in the format 'utility:down' where 'utility' is the category, and 'down' is the specific icon to be displayed. | String                            | —                                               |          |
| `list-button-show-less-icon-position` | Position of the list button’s icon. Valid values include left and right.                                                                                                                  | String                            | `"left"`                                        |          |
| `list-button-show-less-label`         | Label of the button that appears in the list layout, when the number of avatars exceeds the max-count number.                                                                             | String                            | `"Show less"`                                   |          |
| `list-button-show-more-icon-name`     | The Lightning Design System name of the list button icon. Specify the name in the format 'utility:down' where 'utility' is the category, and 'down' is the specific icon to be displayed. | String                            | —                                               |          |
| `list-button-show-more-icon-position` | Position of the list button’s icon. Valid values include left and right.                                                                                                                  | String                            | `"left"`                                        |          |
| `list-button-show-more-label`         | Label of the button that appears in the list layout, when the number of avatars exceeds the max-count number.                                                                             | String                            | `"Show more"`                                   |          |
| `list-button-variant`                 | Variant of the button that appears in the list layout, when the number of avatars exceeds the max-count number.                                                                           | String                            | `"neutral"`                                     |          |
| `max-count`                           | The maximum number of avatars allowed in the visible list. This attribute is ignored if `enable-infinite-loading` is present.                                                             | Number                            | `"5 for stack, 11 for grid and list"`           |          |
| `show-more-button-alternative-text`   | The alternative text used to describe the show more button.                                                                                                                               | String                            | `"Show more"`                                   |          |
| `size`                                | The size of the avatars. Valid values include x-small, small, medium, large, x-large and xx-large.                                                                                        | String                            | `"medium"`                                      |          |
| `variant`                             | Shape of the avatars. Valid values include empty, circle or square.                                                                                                                       | String                            | `"square"`                                      |          |

### Custom Events

#### `actionclick`

The event fired when the user clicks on an action.

The `actionclick` event returns the following parameters.

| Parameter | Type   | Description            |
| --------- | ------ | ---------------------- |
| `name`    | string | The avatar group name. |

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

#### `avataractionclick`

The event fired when the user clicks on an avatar action.

The `avataractionclick` event returns the following parameters.

| Parameter    | Type   | Description         |
| ------------ | ------ | ------------------- |
| `item`       | object | The avatar detail.  |
| `name`       | string | The action name.    |
| `targetName` | string | Name of the avatar. |

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

#### `avatarclick`

The event fired when the user click on an avatar.

The `avatarclick` event returns the following parameters.

| Parameter | Type   | Description         |
| --------- | ------ | ------------------- |
| `item`    | object | The avatar detail.  |
| `name`    | string | Name of the avatar. |

The event properties are as follows.

| Property   | Value | Description                                                                        |
| ---------- | ----- | ---------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                             |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event.         |
| composed   | false | This event does not propagate outside of the component in which it was dispatched. |

#### `itemsvisibilitytoggle`

The event fired when you click on the show more/less button that appears at the end of the list `layout`, if a `max-count` value is present and `enable-infinite-loading` is not present.

The `itemsvisibilitytoggle` event returns the following parameters.

| Parameter            | Type    | Description                                                                                                                                  |
| -------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `show`               | boolean | True if avatars are currently hidden and the click was meant to show more of them. False if the click was meant to hide the visible avatars. |
| `visibleItemsLength` | number  | Length of the currently visible items.                                                                                                       |

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

#### `loadmore`

The event fired when you scroll to the end of the avatar group. This event is fired only if `enable-infinite-loading` is true.

The `loadmore` event doesn't return any parameters.

| 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-avatar-group-avatar-stack-sizing-border`                       | sizing    | `1px`     |
| `--avonni-avatar-group-avatar-stack-color-border`                        | color     | `#ffffff` |
| `--avonni-avatar-group-avatar-stack-styling-border`                      | color     | `#ffffff` |
| `--avonni-avatar-group-show-more-button-neutral-spacing-block-end`       | dimension | `0`       |
| `--avonni-avatar-group-show-more-button-neutral-spacing-block-start`     | dimension | `0`       |
| `--avonni-avatar-group-show-more-button-neutral-spacing-inline-end`      | dimension | `1rem`    |
| `--avonni-avatar-group-show-more-button-neutral-spacing-inline-start`    | dimension | `1rem`    |
| `--avonni-avatar-group-show-more-button-neutral-color-background`        | color     | `#ffffff` |
| `--avonni-avatar-group-show-more-button-neutral-color-background-active` | color     | `#f3f3f3` |
| `--avonni-avatar-group-show-more-button-neutral-color-background-hover`  | color     | `#f3f3f3` |
| `--avonni-avatar-group-show-more-button-neutral-color-border`            | color     | `#c9c9c9` |
| `--avonni-avatar-group-show-more-button-neutral-color-border-active`     | color     | `#c9c9c9` |
| `--avonni-avatar-group-show-more-button-neutral-color-border-hover`      | color     | `#c9c9c9` |
| `--avonni-avatar-group-show-more-button-neutral-text-color`              | color     | `#0176d3` |
| `--avonni-avatar-group-show-more-button-neutral-text-color-active`       | color     | `#014486` |
| `--avonni-avatar-group-show-more-button-neutral-text-color-hover`        | color     | `#014486` |
| `--avonni-avatar-group-show-more-button-neutral-radius-border`           | dimension | `0.25rem` |
| `--avonni-avatar-group-show-more-button-neutral-sizing-border`           | sizing    | `1px`     |

## Key Considerations

* **Overflow:** `max-count` controls how many avatars show before the rest collapse; defaults differ by layout.
* **Per-item config:** Item properties like `initials`, `alternativeText`, `presence`, `status`, and `actions` are set on each object in `items`.
* **Layout attributes:** Use `layout-attributes` to customize layout-specific behavior such as the list show more/less labels.
* **Accessibility:** Provide `keyboard-assistive-text` and per-item `alternativeText` for screen reader and keyboard users.
* **Best Practice:** Set a sensible `max-count` so the group stays compact, and provide `alternativeText` on each item for accessibility.

***

## Troubleshooting Common Issues

* **Avatars not showing:** Confirm `items` is a non-empty array and each item has identifying data (`initials`, `src`, or `fallbackIconName`).
* **Too many or too few visible:** Adjust `max-count`; remember defaults differ between `stack` and `grid`/`list`.
* **Show more/less missing:** It only appears in `list` layout when items exceed `max-count`.
* **If issues persist:** Contact our support team at <support@avonni.app> for assistance.


---

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