Avatar group
An avatar group is a compact, overlapping roster of people: the travellers on a trip, the collaborators on a plan.
Installation
npx shadcn@latest add @flyingsalmon/avatar-groupUsage
import { AvatarColor } from '@/components/ui/avatar'
import { AvatarGroup } from '@/components/ui/avatar-group'
const travellers = [
{ id: 'brian', name: 'Brian Nguyen', color: AvatarColor.Sky },
{ id: 'linh', name: 'Linh Tran', color: AvatarColor.Teal },
]
export function TripTravellers() {
return <AvatarGroup items={travellers} aria-label="Trip travellers" />
}Examples
Sizes
The two avatar sizes, set once on the group. Use small in a dense row such as a table cell or a comment header.
Overflow
max is the number of avatars shown, not the total. Whenever the roster runs past it, the group adds a +N overflow count, even for one person over. The overflow count is an avatar-shaped circle, not a badge.
Capped count
A roster of 254 would print +250 in a circle that fits two digits. cap stops the printed number at +99 while the overflow count's accessible name still says 250 more. Below the cap the overflow count prints the real number.
On a card
Every avatar wears a ring in the page colour so the faces separate. On a card, set the ring to the card colour with className.
Hanoi in spring
Names beside the group
Hover or focus an avatar and a tooltip names the person, but a touch screen has no such path. When the names matter, write them as text and let the cluster stay decoration.
Brian, Linh and Minh and 2 others
Guidelines
When to use
- To show who is on a trip, a plan, or a row at a glance.
- When the roster can grow without a bound, because the group folds the overflow into one overflow count.
When not to use
Do and don’t
- DoShow about four faces and let the overflow count carry the rest.The group is a glance at who is going, never the full roster. Capping the faces ends every row at the same width, so a list of trips lines up.
- Don’tLeave the tooltip as the only place that says who is going.Touch screens cannot open it, and the faces are a glance, not the record. Wherever the reader must know who is going, write the names as text.
Accessibility
| Key | Description |
|---|---|
| Tab | Enters the group on its first named avatar. The group is one tab stop, and Tab leaves it. |
| ArrowRightArrowLeft | Moves to the next or previous avatar, then the overflow count. Focus does not wrap. |
| HomeEnd | Jumps to the first or last stop. |
| Escape | Closes the open tooltip and leaves focus where it is. |
The wrapper is role="group" and forwards aria-label. Each avatar and the overflow count is a focusable role="img" named by the person, or by alt when there is no name, and the overflow count is named N more. An item with neither a name nor an alt is hidden from assistive technology, gets no tooltip, and the arrow keys skip it.
Focus does everything hover does, and also turns the ring around the focused face orange, so the indicator stays visible on a group of one where nothing moves. Pressing an avatar does nothing, because nothing here is a button; it only closes the tooltip.
API
AvatarGroup
Also takes every <div> attribute except children. Render it inside a TooltipProvider, once at your app root. Hovering a face parts the row past the group’s own box, so keep it out of any container that clips its overflow.
| Prop | Type | Default | Description |
|---|---|---|---|
| items | AvatarGroupItem[] | Required | The roster, in order. Each item takes name, src, color, and alt as Avatar does, plus an optional id used as its key. |
| size | AvatarSize | AvatarSize.Default | Set once on the group and passed to every avatar and the overflow count. Items carry no size of their own. |
| max | number | 4 | How many avatars show before the overflow count. Values below 1 count as 1. |
| cap | number | – | The largest number the overflow count prints. The overflow count’s accessible name always states the true count. |
| aria-label | string | – | Names the group, which is announced as one unit. Say whose faces these are, such as Trip travellers. |