Avatar Group
FreeShow 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-groupPlayground
Installation
npx wunderui-cli add avatar-groupWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar"
import type { AvatarGroupProps } from "@/components/ui/avatar"Then use it:
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.
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.
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.
Keyboard interactions
The group is a plain container. Only an interactive count is a control, and it is a native button.
- TaborShift+Tab
- 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.
- 1
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.
- 2
Each person: an Avatar with initials or an image. Give all avatars in one group the same size.
- 3data-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.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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. |
| max | number | 3 | With : how many faces show before the count. Default 3. |
| people | Person[] | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| interactive | boolean | — | 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 . |
| Prop | Type | Default | Description |
|---|---|---|---|
| people required | Person[] | — | |
| max | number | 3 | |
| size | "sm" | "xs" | "default" | "sm" |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("avatar-group")npx wunderui-cli add avatar-groupThe full library index for assistants is at /llms.txt.