Avatar Group

The row of overlapping faces that shows who is on a project, in a thread, or assigned to a task — with the "+3" that keeps it from taking over the layout.

import { AvatarGroup } from "@/components/ui/avatar-group";

const PEOPLE = [
  { id: "1", name: "Alice Nguyen", src: "/avatars/alice.jpg" },
  { id: "2", name: "Bruno Costa" },
  { id: "3", name: "Chen Wei", src: "/avatars/chen.jpg" },
];

<AvatarGroup people={PEOPLE} max={4} />;

Self-contained — no separate avatar dependency to install. Avatar is exported too, for the places you need a single one.

Images and initials

src is optional. Without it — or when the image fails to load, which is the common case with user-supplied URLs — the avatar falls back to initials derived from name. Pass initials to override, which matters for names the two-word heuristic gets wrong.

Overflow

max counts avatars, not people: with max={4} and six people you see four faces and a +2. The counter's tooltip lists everyone it hides, so the information is still reachable.

Sizes

xs, sm, default, and lg. The overlap scales with the size, so the stack keeps its proportions.

<AvatarGroup people={PEOPLE} size="xs" max={6} />

Ring color

Overlapping avatars are separated by a ring that punches a gap in the surface behind them, so it has to match that surface. It defaults to var(--background), which is right on the page but wrong anywhere the background differs — inside a Card, a popover, or a muted panel, where the ring reads as a dark outline in dark mode.

Set --avatar-ring on any ancestor to correct it. Custom properties inherit, so one declaration covers every avatar inside, including standalone Avatar elements:

<Card className="[--avatar-ring:var(--card)]">
  <AvatarGroup people={PEOPLE} />
</Card>

In the default theme the light palette gives --background and --card the same value, so a missing override only shows up in dark mode. Check both.

Props

Prop	Description
`people`	`{ id?, name, src?, initials?, href? }[]`. `href` makes the avatar a link.
`max`	Avatars shown before collapsing. Defaults to `4`.
`size`	`"xs"`, `"sm"`, `"default"`, `"lg"`.
`tooltips`	Name on hover and focus. On by default.
`aria-label`	Labels the group. Defaults to `"People"`.

Accessibility

Names are not decoration: an avatar rendering an image uses the name as its alt, and an avatar rendering initials keeps the full name in visually hidden text — so the group reads as a list of people rather than "image, image, image". The overflow counter announces "3 more".

Tooltips only appear on hover and focus, so the name must also exist in the accessible name for touch users. That is why both are present.