Avatar group

• Type: Component (data)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/avatar-group
• Markdown: https://ui.xzero.co.uk/components/avatar-group/markdown
• Registry item: https://mcp.xzero.co.uk/r/avatar-group.json
• Source file: registry/components/avatar-group/avatar-group.tsx
• Dependencies: motion
• Keywords: identity, people, react avatar group, avatar stack, overlapping avatars, team members avatars, avatar overflow count, collaborators list

When to use

• 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.

When not to use

• Use avatar for a single person.
• Use a list or sortable-data-table when people need to see every name and role.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/avatar-group

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { AvatarGroup } from "@/components/xzero/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" />;
}

API reference

AvatarGroup

An overlapping stack of avatars with a +N overflow chip.

Prop	Type	Default	Description
members (required)	{ name: string; src?: string; status?: "online" | "offline" }[]	–	People in display order. Names double as keys, so keep them unique.
max	number	4	Avatars shown before the rest collapse into the overflow count.
size	"sm" | "md" | "lg"	"md"	Size passed to each avatar and the overflow chip.
label	string	"Team members"	Accessible name for the group, also used in the overflow label.

Accessibility

• 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.

Motion

• 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.

Responsive behavior

• 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.

Performance

• 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

• 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.

Related

• Avatar: A compact identity marker for people and accounts.
• Card: A contained group of related content and actions.
• User menu: Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.

Also in avatars

• Badge: A small label for status, category, or metadata.
• Presence stack: Avatars of the people here now: joins pop in as the stack reflows, a counter rolls past the limit, dots show typing and idle, and hover fans it out with a gliding name label.

Guidance for AI tools

Avatar group: Show a team or set of contributors in a small space. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt