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.

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

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

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

itemactionclick

The event fired when the user clicks on an item's action.

The itemactionclick event returns the following parameters.

Parameter	Type	Description
name	string	Action name.
targetName	string	Name of the item to which the action belongs.

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.

itemclick

The event fired when the user click on an item.

The itemclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the clicked 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.

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.

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.

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.

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 [email protected] for assistance.