Avatar Group
Freev1.0.0A stack of avatars with a +N count and names on hover.
Build for your project
Code/install build
Usage
Import it and pass your content. The props that matter most are listed next.
Example
import { AvatarGroup, type GroupPerson } from "@/components/ui/notchset/avatar-group";
const reviewers: GroupPerson[] = [
{ id: "mk", name: "Maya Kerr", role: "ML lead", presence: "on" },
{ id: "jw", name: "Jonas Weber", role: "Evals", presence: "away" },
{ id: "ar", name: "Ana Ruiz", role: "Infra" },
{ id: "lp", name: "Lee Park", role: "Design" },
{ id: "so", name: "Sam Osei", role: "Support" },
];
export function Reviewers() {
return <AvatarGroup aria-label="Reviewers" people={reviewers} max={4} />;
}Props
people–{ id, name, role?, presence?, tone? }[]In order; the first max are shown.
max–numberAvatars before +N (4).
Anatomy
- Uses Avatar's node and tones.
- No primitive needed: one file serves both builds.
- Hover and focus share one callout.
AvatarGroupdata-slot="avatar-group"The group.
Source
components/ui/notchset/avatar-group.tsx
Loading the code
Build for your project
Code/install build
Installation
Base UI
pnpm dlx shadcn@latest add https://notchset.dev/r/avatar-group.jsonRadix
pnpm dlx shadcn@latest add https://notchset.dev/r/radix-nova/avatar-group.jsonFree, no account or key. Use the command for your project's primitives: a radix-*, new-york or default style in components.json is Radix, a base-* style is Base UI. With the @notchset registry added, @notchset/<name> picks for you.
Install by hand
- 1. No extra packages: React and Tailwind CSS v4 are enough.
- 2. Copy the files to these paths (the source, or save them all as a .zip)
- components/ui/notchset/avatar-group.tsx
- components/ui/notchset/avatar.tsx
- lib/beautiful-ui/notchset/instrument.tsx
- lib/beautiful-ui/notchset/root.ts
- lib/beautiful-ui/notchset/calendar.tsx
- 3. No stylesheet needed.
- 4. Install what it builds on first: shadcn's cn helper (lib/utils.ts, from npx shadcn init), Avatar, the theme foundation (its tokens and base styles)
Styles didn't apply?
The CLI adds the styles to the CSS file named in components.json (tailwind.css). Check that it points at your global stylesheet, that the project uses Tailwind CSS v4, and that the file is imported in your root layout. Installed by hand: paste styles.css into that file.
For coding agents
Give your coding assistant the Markdown guide instead of screenshots.
Use it for
- Who's on something: reviewers, viewers, assignees
Use something else when
- A full member list: use a table
Mistakes to avoid
- Keep ids stable so members animate rather than remount
Agents find it by
- avatar group, avatar stack, reviewers, participants, members, facepile, Notchset
Where agents read it
- Guide for this component: https://notchset.dev/md/avatar-group.md
- Every component, for tools without MCP: /llms.txt
- MCP server:
https://notchset.dev/api/mcp(setup)
Behaviour
Keyboard
- Tab
- Each avatar, then +N, naming each in the callout
Accessibility
- A labelled group; every avatar is a focusable, labelled button
- Hidden members are aria-hidden and unfocusable; the chip names them
Motion
- Add
- The new avatar pops from 40% (380ms, +80ms); the group widens (420ms)
- Remove
- It shrinks away (220ms); the rest glide (420ms)
- Callout
- Glides between avatars (260ms)
Responsive
- Width follows the count.
Performance
- Absolutely placed; changes are left, scale and opacity.
Changelog
v1.0.0 · 2026-10-02
First release
