Skip to content
WunderUI

Avatar Group

Free

Show the people on a project or document as a row of avatars, overlapping or spaced, with a count or a button for the rest.

npx wunderui-cli add avatar-group

Playground

+3

Installation

bash
npx wunderui-cli add avatar-group

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar"
import type { AvatarGroupProps } from "@/components/ui/avatar"

Then use it:

tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar-group"

export function Team() {
  return (
    <AvatarGroup>
      <Avatar color="indigo">
        <AvatarFallback>NL</AvatarFallback>
      </Avatar>
      <Avatar color="purple">
        <AvatarFallback>DO</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  )
}

Expected result: You should see two overlapping avatars, NL and DO, and a +3 circle of the same size at the end.

When to use

Use Avatar Group for

  • The people on a project, document or meeting, in a header or a row
  • A short list of people where you decide how many faces show
  • A row of faces with a button that opens everyone who is not shown
  • A list of people passed as data, cut at a limit with a +N count worked out for you (people)

Use something else for

  • Avatar for one person, workspace or team
  • Avatar label for people listed with a name and a role in a table or a list

Layout

Overlap saves room in a header. Spaced keeps every face whole, for a short list where each person matters.

+3

Overflow

The group shows every child you give it. Cut the list yourself and add a count, or a button that opens the rest.

Sizes

The group has no size of its own. It follows its avatars, and the count follows with it.

+3

People list

Pass people instead of children and the group draws the avatars itself, overlapping by 4 px, cut at max (three by default) with a +N avatar of the same size for the rest. size picks the avatar (sm 24, xs 28, default 36, lg 40, xl 44 px; sm by default). Hovering a face lifts it and shows the name in a Tooltip. Its rings take the colour behind the group (--surface), so they match a card, a popover or a hovered or selected row. It replaces AvatarStack.

NL
DO
PR
+3

Keyboard interactions

The group is a plain container. Only an interactive count is a control, and it is a native button.

TaborShiftTab
Moves focus to or away from an interactive count, and to any interactive avatar in the group, in the order they are written.
EnterorSpace
Presses the focused count, for example to open the list of the people who are not shown.

The hover lift follows the mouse only: moving focus with the keyboard does not lift an avatar.

Behavior and motion

What the group does with state, content, the DOM and motion.

Every child is shown
The group renders every child it gets and does not count, cut or reorder them. Later avatars sit on top of earlier ones.
Overlap and rings
In overlap layout each avatar overlaps the one before by 12 px and gets a 2 px ring in the surface colour. In spaced layout the avatars keep a 6 px gap and get no ring.
Count
A static count is a muted circle with the text you pass, such as +3. As a button it has a border: hover and open use the page tone, a press the subtle tone, disabled dims it to 40 %.
Size
The group has no size setting. The count takes the size of the avatars, 24, 28, 36, 40 or 44 px, so give every avatar the same one.
Names for screen readers
A static count is read as plain +3, so add visually hidden text like more people after it, or use an interactive count with an aria-label. Hide the avatars when names are listed elsewhere.
Motion
Hovering an avatar lifts it by 4 px and scales it to 1.05; neighbours lift less the farther away they are. Only transform animates.
Reduced motion
With reduced motion on, the lift is off: hovering changes nothing.

Anatomy

The parts the component is made of. Each one renders a you can target from CSS.

NL
DO
+3
  • The row. It overlaps its avatars with a ring in the surface colour, or spaces them with a 6 px gap; hovering one lifts it and nudges its neighbours, except with reduced motion.

  • Each person: an Avatar with initials or an image. Give all avatars in one group the same size.

  • data-slot="avatar-group-count"Optional

    The +N circle at the end for everyone not shown, as a static count or a button. It takes the size of the avatars.

  • data-slot="avatar-group"
  • data-slot="avatar"
  • data-slot="avatar-check"Optional
  • data-slot="avatar-fallback"
  • data-slot="avatar-image"
  • Optional

Best practices

  • Do

    Cut the list yourself and put the rest in the count as +3. The group renders every child it gets; it does not count or hide anyone.

  • Do

    Make the count a button when people can open the rest. Give it an aria-label such as Show 3 more people and aria-expanded.

  • Do

    Place the group on a surface that sets the surface colour, such as a Card. The rings take that colour, so each avatar reads as cut out of the background.

  • Do

    Pick overlap for a header or a row where room is short, and spaced for a short list where each face should stay whole.

  • Don’t

    Don't mix avatar sizes in one group. The overlap and the count circle assume one size for every avatar.

  • Don’t

    Don't use a group for a single person, or for a list people should read name by name. Use Avatar, or AvatarLabel with a name.

  • Do

    At sm and xs the faces overlap by 2 px so both initials stay readable; do not tighten them further with your own spacing.

API reference

Avatar Group renders a div and the count a div or, when interactive, a button. They take the native attributes of that element, such as className and onClick.

The row. It overlaps its avatars with a ring in the surface colour, or spaces them with a 6 px gap; hovering one lifts it and nudges its neighbours, except with reduced motion.

PropTypeDefaultDescription
layout"overlap" | "spaced"— stacks the avatars with a 12 px overlap and a ring in the surface colour. puts a 6 px gap between them.
maxnumber3With : how many faces show before the count. Default 3.
peoplePerson[]—A list of people: the group renders their avatars itself, overlapping by 4 px (2 px at and , so the second initial is not hidden under the next face), cut at with a "+N" avatar. Hovering a face lifts it and shows the name in…
size"xs" | "sm" | "default" | "lg" | "xl""sm"With : the avatar size, 24 px, 28 px, 36 px, 40 px, 44 px. Default .

The +N circle at the end for everyone not shown, as a static count or a button. It takes the size of the avatars.

PropTypeDefaultDescription
interactiveboolean—Renders the count as a button with hover, open, pressed and focus states, for opening the rest of the people. A button takes , and . Without it the count is a static .

PropTypeDefaultDescription
people requiredPerson[]—
maxnumber3
size"sm" | "xs" | "default""sm"

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("avatar-group")
Installnpx wunderui-cli add avatar-group

The full library index for assistants is at /llms.txt.