AvatarGroup
Overlapping stack of avatars with a max cap and an i18n-labelled +N overflow chip
Category: display · WCAG 2.2-AA · avatar, group, stack, overflow, display
States
- default
Props
| Prop | Type | Default | Description |
|---|---|---|---|
max | number | — | Cap the number of visible avatars |
total | number | — | Override the total count used for the +N chip |
spacing | 'sm' | 'md' | 'lg' | md | Spacing between items. |
isGrid | boolean | false | When true, lays the avatars out in a grid instead of an overlapping stack. |
labels | AvatarGroupLabels | — | Overrides for the component’s user-visible strings (i18n). |
Design tokens
--cascivo-color-surface--cascivo-color-text-muted--cascivo-space-2--cascivo-text-xs
When to use
- Showing several people compactly as an overlapping stack (collaborators, attendees, reviewers)
- Capping a long list of avatars with a +N overflow chip
- A facepile in a card header, table cell, or activity row
When not to use
- A single identity with a name — use User or Avatar
- A selectable list of people — use a list/menu with checkboxes
How to build an accessible AvatarGroup in React →
Examples
Basic
<AvatarGroup><Avatar fallback="A" /><Avatar fallback="B" /><Avatar fallback="C" /></AvatarGroup>With max
<AvatarGroup max={3}>{users.map((u) => <Avatar key={u.id} src={u.src} alt={u.name} />)}</AvatarGroup>Grid
<AvatarGroup isGrid max={8}>{avatars}</AvatarGroup>