Avatar group
Show a team or set of contributors in a small space.
pnpm dlx shadcn@latest add @uiarc/avatar-groupLive · keyboard ready
- Showing who owns or edits something in a header, card, or table cell.
- Collaborator stacks where people join and leave while the page is open.
- Long member lists that should collapse into a +N chip.
- Use avatar for a single person.
- Use a list or sortable-data-table when people need to see every name and role.
Installation
Add Avatar group with the shadcn CLI, or copy the source by hand.
pnpm dlx shadcn@latest add @uiarc/avatar-groupAdds the component and its local dependencies, and installs motion. First time? Add the @uiarc registry to components.json, or use the full URL:
example.tsx
import { AvatarGroup } from "@/registry/components/avatar-group/avatar-group"; const team = [ { name: "Maya Chen", src: "/people/maya.jpg", status: "online" as const }, { name: "Leo Park" }, { name: "Sara Ruiz" }, { name: "Tom Hale" }, { name: "Ines Ma" },]; export function Collaborators() { return <AvatarGroup members={team} max={3} label="Editors" />;}AvatarGroup
An overlapping stack of avatars with a +N overflow chip.
PropTypeDefaultDescription
membersRequired{ name: string; src?: string; status?: "online" | "offline" }[]–People in display order. Names double as keys, so keep them unique.maxnumber4Avatars shown before the rest collapse into the overflow count.size"sm" | "md" | "lg""md"Size passed to each avatar and the overflow chip.labelstring"Team members"Accessible name for the group, also used in the overflow label.- Renders role="group" with the label as its name.
- The overflow chip is role="img" labelled like "2 more editors".
- Each avatar keeps its own name and status label.
- Joining or leaving members open and close their slot on a spring, so the stack slides instead of jumping.
- The overflow count rolls up when it grows and down when it shrinks.
- Hover fans the stack apart in CSS. Reduced motion removes the fan and swaps counts with a plain fade.
- The stack is inline-flex and does not wrap; lower max on narrow rows so it stays compact.
- The hover fan applies only on hover-capable fine pointers, so touch taps do not spread the stack.
- Only max avatars render; the rest collapse into one overflow chip, so long member lists stay cheap.
- Joins and leaves animate slot width on a spring; the fan is plain CSS transforms.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Use for presence and ownership in headers, cards, and table cells. Use avatar for one person.
- Pass the full member list and let max handle truncation; do not slice it yourself or the overflow count is lost.
The full library index for assistants is at /llms.txt.
