Avatar group

Show a team or set of contributors in a small space.

identitypeople

Preview

Live · keyboard ready

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.

shadcn CLI

Also installs (2)

manicat-foundation
avatar

Manual install(+)

registry.jsonjson

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "avatar-group",
  "type": "registry:ui",
  "title": "Avatar group",
  "description": "Show a team or set of contributors in a small space.",
  "categories": [
    "data"
  ],
  "dependencies": [
    "motion"
  ],
  "registryDependencies": [
    "https://manicat.viraza.net/r/manicat-foundation.json",
    "https://manicat.viraza.net/r/avatar.json"
  ],
  "files": [
    {
      "path": "registry/components/avatar-group/avatar-group.tsx",
      "type": "registry:component",
      "target": "@components/manicat/avatar-group/avatar-group.tsx"
    },
    {
      "path": "registry/components/avatar-group/avatar-group.module.css",
      "type": "registry:component",
      "target": "@components/manicat/avatar-group/avatar-group.module.css"
    },
    {
      "path": "registry/components/avatar/avatar.tsx",
      "type": "registry:component",
      "target": "@components/manicat/avatar/avatar.tsx"
    },
    {
      "path": "registry/components/avatar/avatar.module.css",
      "type": "registry:component",
      "target": "@components/manicat/avatar/avatar.module.css"
    }
  ],
  "docs": "Docs and live preview: https://uiarc.dev/components/avatar-group",
  "meta": {
    "tier": "free",
    "kind": "component",
    "docs": "https://manicat.viraza.net/components/avatar-group",
    "markdown": "https://uiarc.dev/components/avatar-group/markdown",
    "tags": [
      "identity",
      "people"
    ]
  }
}

Usage

Install the component, then copy this into your app. Change the content and the props to fit your screen.

example.tsxtsx

"use client";

import { AvatarGroup } from "@/components/manicat/avatar-group/avatar-group";

export function AvatarGroupExample() {
  return (
    <AvatarGroup
      members={[
        { name: "Ada Lovelace", src: "https://i.pravatar.cc/96?img=47" },
        { name: "Grace Hopper", src: "https://i.pravatar.cc/96?img=32" },
        { name: "Alan Turing", src: "https://i.pravatar.cc/96?img=13" },
        { name: "Katherine Johnson", src: "https://i.pravatar.cc/96?img=45" },
        { name: "Barbara Liskov", src: "https://i.pravatar.cc/96?img=44" },
      ]}
    />
  );
}

Examples

Real screens rather than isolated props. Switch to Code to copy a whole example into your project.

Project members Overlapping avatars that collapse into a +N when the list is long.

Live · keyboard ready

5 members

project-members-overlapping-avatars-that-collapse-into-a-n-when-the-list-is-long-.tsxtsx

"use client";

import { AvatarGroup } from "@/components/manicat/avatar-group/avatar-group";

export function AvatarGroupMembersExample() {
  return (
    <div className="flex items-center gap-3">
      <AvatarGroup
        members={[
          { name: "Ada Lovelace", src: "https://i.pravatar.cc/96?img=47" },
          { name: "Grace Hopper", src: "https://i.pravatar.cc/96?img=32" },
          { name: "Alan Turing", src: "https://i.pravatar.cc/96?img=13" },
          { name: "Katherine Johnson", src: "https://i.pravatar.cc/96?img=45" },
          { name: "Barbara Liskov", src: "https://i.pravatar.cc/96?img=44" },
        ]}
      />
      <span className="text-sm text-(color:--text-muted)">5 members</span>
    </div>
  );
}

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.