AvatarGroup

AvatarGroup shows a group of people or entities as avatars laid side by side, stacked, or split inside a circle.

Use it to show who takes part in a meeting, document or project. Past maxAvatars, the remaining members go into a “+N” button that opens a Popover with the full list.

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX

// npm install yugen-uiimport { AvatarGroup, AvatarGroupItem } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

Layout

spread (default); stack, with a ring that separates the overlapping avatars; pie, which splits 2–3 avatars inside one circle.

Size

Same size scale as Avatar: 20, 24, 32 (default), 40, 48, 64, 96.

Overflow & full list

maxAvatars limits the number of slots (the overflow button included). Click “+N” or “…” to see the list in a Popover.

Pie

The most compact option for tight spaces; the whole circle is a button that opens the member list.

Usage

Set an aria-label that describes the group (e.g. “Project members”).
Use stack where space is tight and spread when each person needs to be clearly visible.
Use the same size for every avatar in the group.

Don't

Don't show more than 5–6 avatars at once. Use maxAvatars.
Don't use the pie layout for large groups: the circle only fits 2–3 avatars.
Don't use AvatarGroup for a single person. Use Avatar or Persona.

Props

Prop · Type	Default	Description
layout"spread" \| "stack" \| "pie"	Default: "spread"	How the avatars are arranged.
size20 \| 24 \| 32 \| 40 \| 48 \| 64 \| 96	Default: 32	Size of every avatar in the group.
maxAvatarsnumber	Default: 5	Maximum number of slots (the overflow button included); doesn't apply to pie.
overflowIndicator"count" \| "icon"	Default: "count"	The overflow button shows “+N” or a “…” icon.
overflowLabelstring	Default: —	Label read after the count on the button that opens the list ("+2 …"); with overflowIndicator="icon" it is the button's whole name.
AvatarGroupItem.name / src / colorstring / string / AvatarColor	Default: color "colorful"	Details of each member.
AvatarGroupItem.image / renderImage / fallbackDelay / onLoadingStatusChangePick<AvatarProps, …>	Default: —	Image options, as on Avatar.

Messages

Text built into the component: labels, aria-labels, screen reader announcements.

English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.

messages.avatarGroup

Key · Type	Default (English)	messagesVi
liststring aria-label danh sách thành viên trong popover.	Default (English)`"Members"`	messagesVi`"Danh sách thành viên"`
viewAll(count: number) => string Tên nút ở dạng pie (mở danh sách đầy đủ).	Default (English)(count) => (count === 1 ? "View 1 member" : `View ${count} members`)	messagesVi(count) => `Xem ${count} thành viên`
viewMore(count: number) => string Tên nút tràn "+N" / "…".	Default (English)(count) => (count === 1 ? "View 1 more member" : `View ${count} more members`)	messagesVi(count) => `Xem thêm ${count} thành viên`