Avatar Group
Overlapping avatars that fan apart on hover, with names that spring up above each one.
- Category: Display
- Licence: Free, MIT
- Built with: React 19, Tailwind CSS 4, Motion
- Dependencies: motion, clsx, tailwind-merge
Examples
Avatar Group
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
people | { name: string; src?: string }[] | — | |
max | number | 5 | |
size | number | 40 |
About Avatar Group
Avatar Group stacks avatars with an overlap and fans them apart on hover, with each name springing up above its face. A max shows a plus count for the rest.
Avatar Group is a display component for React 19, styled with Tailwind CSS 4 and animated with Motion. It drops into Next.js, Vite, Remix or Astro through the shadcn CLI as a single file you own.
When to use Avatar Group
- Team and collaborator lists.
- Social proof near sign-up forms.
- Assignees on tasks and issues.
- Event attendees.
How it works
Spacing animates on hover with springs and the name tooltips stagger in. Each avatar has alt text, and the overflow count is announced.
Interactive parts are buttons or links with accessible names, decorative layers are hidden from assistive tech, and everything is reachable by keyboard. With prefers-reduced-motion on, it holds still or settles instantly instead of animating.
Customizing Avatar Group
Every prop is documented in the API reference above with its type and default. The ones you will reach for first are listed here.
The Customize panel next to the preview lets you change max, size live, and the Code tab updates to match, so the snippet you copy already carries your values.
- people ({ name: string; src?: string }[]).
- max (number, default 5).
- size (number, default 40).
Goes well with Avatar Group
Avatar Group is already composed into 5 ready-made sections, so you can see it in context or install the whole block.
- Hero Rotating: Hero section
- Hero Event: Hero section
- FAQ Chat: FAQ section
- FAQ Support: FAQ section
- Accordion: An animated React accordion: height springs open, the chevron flips, content fades in
- Number Ticker: An animated React number ticker: each digit rolls on its own wheel
- Marquee: A CSS-only infinite React marquee with faded edges and pause on hover
- Theme Toggle: A React dark mode toggle: the sun eclipses into a moon and the theme spreads out
- Copy Button: A React copy button whose icon blurs into a drawn check, then swaps back
Install Avatar Group
npx shadcn@latest add https://charcoalui.com/r/avatar-group.jsonAvatar Group is free and MIT licensed. The command copies avatar-group.tsx into components/ui and installs clsx, tailwind-merge; you can also copy the source from the Code tab by hand.
It pairs well with Stack Cards, a Pro piece: Cards pin as you scroll and stack on top of each other, the ones underneath shrinking back.
Frequently asked questions
- What happens when there are more avatars than max?
- The extra ones collapse into a plus count, which is announced to screen readers.
- How do I install Avatar Group?
- Run npx shadcn@latest add https://charcoalui.com/r/avatar-group.json. The shadcn CLI copies avatar-group.tsx into components/ui and installs motion, clsx, tailwind-merge. You can also copy the source from this page by hand.
- Is Avatar Group free for commercial use?
- Yes. Avatar Group is MIT licensed: use it in any personal or commercial project and change it however you like.
- Does Avatar Group work with Next.js?
- Yes. It is a client component for React 19 styled with Tailwind CSS 4, so it works in the Next.js App Router and Pages Router, Vite, Remix and Astro.
- Can an AI coding agent install Avatar Group?
- Yes. Connect the Charcoal UI MCP server (https://charcoalui.com/mcp) to Claude Code, Cursor or any MCP client; get_component returns Avatar Group's props and source and get_install_command returns the exact command.