Avatar Group

Data Display

Stacks overlapping avatars and collapses the overflow into a count badge.

AvatarGroup renders up to a maximum number of avatars, each wrapped in a background ring so they stack cleanly. Surplus members are shown as a +N circle.

npx shadcn@latest add avatar-group

Default

Avatars overlap with a ring, initials are used as a fallback.

Preview

Live

ALATGHLT

tsx

1<AvatarGroup
2  srcs={[
3    "https://i.pravatar.cc/64?img=5",
4    "https://i.pravatar.cc/64?img=12",
5    "https://i.pravatar.cc/64?img=32",
6    "https://i.pravatar.cc/64?img=47",
7  ]}
8  names={["Ada Lovelace", "Alan Turing", "Grace Hopper", "Linus Torvalds"]}
9/>

Overflow

Pass max and total to collapse extra members into a count badge.

Preview

Live

ALATGHLT

tsx

1<AvatarGroup
2  srcs={[...]}
3  names={["Ada", "Alan", "Grace", "Linus"]}
4  total={12}
5  max={4}
6/>

API reference

All props of the underlying Base UI primitive are forwarded. The table below documents the Shelf-specific props.

Prop	Type	Description
srcs	string[]= []	Image URLs rendered in order.
names	string[]= []	Used for alt text and initials fallback.
max	number= 4	Maximum avatars rendered before collapsing.
total	number	Total member count for the overflow badge.