Skip to content
flyingsalmon

Avatar group

An avatar group is a compact, overlapping roster of people: the travellers on a trip, the collaborators on a plan.

+1

Installation

npx shadcn@latest add @flyingsalmon/avatar-group

Usage

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.

+3
+1

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.

+99
+3

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

12 places

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.

+2

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

  • Use Avatar to mark a single person, because the group adds overlap and a tooltip a lone mark does not need.
  • Use Badge for a count with no people behind it, such as places or days.
  • Use Table when each person needs an action, such as removing a traveller, because nothing in the group is clickable.

Do and don’t

  • Do
    Show 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’t
    Leave 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

KeyDescription
TabEnters the group on its first named avatar. The group is one tab stop, and Tab leaves it.
ArrowRightArrowLeftMoves to the next or previous avatar, then the overflow count. Focus does not wrap.
HomeEndJumps to the first or last stop.
EscapeCloses 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.

PropTypeDefaultDescription
itemsAvatarGroupItem[]RequiredThe roster, in order. Each item takes name, src, color, and alt as Avatar does, plus an optional id used as its key.
sizeAvatarSizeAvatarSize.DefaultSet once on the group and passed to every avatar and the overflow count. Items carry no size of their own.
maxnumber4How many avatars show before the overflow count. Values below 1 count as 1.
capnumber–The largest number the overflow count prints. The overflow count’s accessible name always states the true count.
aria-labelstring–Names the group, which is announced as one unit. Say whose faces these are, such as Trip travellers.

  • Avatar

    The single-person mark the group is built from.
  • Tooltip

    Names each person on hover and focus.
  • Badge

    The marker for a count that has no people behind it.
  • Accessibility

    Keyboard and focus rules every component follows.