Avatar Group

Overview

AvatarGroup renders a horizontal stack of overlapping Avatar components, commonly used to show assigned agents, team members, or participants in a compact trigger or table cell.

Each avatar in the stack:

overlaps the previous one with a configurable offset
shows a white border for separation
elevates z-index on hover so the hovered avatar comes to the front
supports optional tooltips per avatar

Use AvatarGroup in picker triggers, table cells, and assignment displays. For a single identity, use Avatar directly.

Basic Usage

import { AvatarGroup } from '@fsai/shared-ui';

<AvatarGroup
  avatars={agents.map((agent) => ({
    firstName: agent.firstName,
    lastName: agent.lastName,
    profilePicture: agent.profilePictureUrl,
  }))}
  avatarSize={24}
/>

With Tooltips

<AvatarGroup
  avatars={agents.map((agent) => ({
    firstName: agent.firstName,
    lastName: agent.lastName,
    profilePicture: agent.profilePictureUrl,
    tooltip: agent.fullName,
  }))}
  avatarSize={32}
  withTooltip
/>

Pass tooltip on individual avatars for custom text, or set withTooltip to show each person's name on hover.

In A Picker Trigger

AvatarGroup is commonly used as the trigger content for a multi-select Picker:

<Picker multiple value={selectedAgentIds} onChange={setSelectedAgentIds}>
  <Picker.Trigger>
    <AvatarGroup avatars={selectedAgents} avatarSize={24} />
  </Picker.Trigger>
  {/* options */}
</Picker>

This is the pattern documented on the Picker component page for agent assignment.

Props

Prop	Type	Default	Description
`avatars`	`Array<AvatarGroupItem>`	—	Required. Avatar data for each stack member.
`avatarSize`	`number`	`40`	Width and height of each avatar in pixels.
`withTooltip`	`boolean`	—	Enables tooltips showing each avatar's name.
`align`	`'left' \| 'right'`	`'left'`	Stack direction — avatars grow left-to-right or right-to-left.
`offset`	`number`	`0.8 * avatarSize`	Horizontal overlap between avatars.
`rounded`	`'sm' \| 'md' \| 'full'`	`'md'`	Corner radius passed to each `Avatar`.
`className`	`string`	—	Additional classes on the container.

Avatar Item Shape

Prop	Type	Description
`firstName`	`string \| null`	First name for initials fallback.
`lastName`	`string \| null`	Last name for initials fallback.
`profilePicture`	`string \| null`	Profile image URL.
`tooltip`	`string`	Custom tooltip text for this avatar.

Important Conventions

AvatarGroup uses the legacy user prop shape on the underlying Avatar (firstName, lastName, profilePicture).
The container width is calculated from avatarSize, offset, and avatar count.
Avatars are absolutely positioned within the container.
For dense layouts, use smaller avatarSize values such as 24 or 28.

Brand Dashboard And Shared Usage

Pattern	Path	Notes
Agent assignment picker	`fsai/apps/brand-dashboard/src/modules/locations/components/LocationPanel/LocationPanelDetails/LocationPanelDetails.tsx`	`AvatarGroup` as a `Picker` trigger for assigned agents.
Location table cell	`fsai/apps/brand-dashboard/src/modules/locations/utils/index.tsx`	Small avatar stacks in table rows.

Guidelines

Do use AvatarGroup when showing multiple people in a compact space
Do reduce avatarSize for dense table cells and picker triggers
Do enable tooltips when the stacked identities are not obvious
Don't use AvatarGroup for a single person — use Avatar directly
Don't exceed a reasonable stack depth — consider showing a count for very large groups

Avatar Group

On this page