Avatar Group, animated React component
An overlapping stack of avatars that behaves like a dock: the face under the pointer swells and rises, its neighbours lean out of the way and a single name pill glides from face to face. Past a maximum a +N chip opens the rest, and every avatar is focusable from the keyboard.
- Free
- Motion Effects
- Hover
- Spring
Like Avatar Group? 256 more are in Pro.
Pro unlocks all 256 Pro components, every template and block, and everything we release next. Avatar Group stays free.
Play with it
Move the controls and watch it change. Copy code gives you a snippet with only the props you changed.
Props
| Prop | Type | Default | What it does |
|---|---|---|---|
| avatars | AvatarData[] | — | People to show: { src?, alt?, fallback, tooltip?, bgColor? }. Defaults to an example team. |
| size | number | 40 | Avatar diameter in px. |
| overlap | number | 10 | Pixel overlap between neighbours. |
| max | number | — | Show at most this many, then a +N chip that expands the rest. |
| hoverAnimation | "lift" | "scale" | "rotate" | "up" | "none" | "lift" | How faces near the pointer react: lift swells, rises and spreads; scale only swells; rotate fans; up only rises. |
| hoverScale | number | 1.3 | Largest scale a face reaches right under the pointer. |
| showTooltips | boolean | true | Show the gliding name pill. |
| borderWidth | number | 2 | Width of the ring around each face, in px. |
| borderColor | string | — | Ring colour. Defaults to white, or the dark surface colour in dark mode. |
| entranceAnimation | "none" | "fade" | "flip" | "slide" | "scale" | "bounce" | "scale" | How faces appear on mount. |
| entranceStagger | number | 0.05 | Seconds between each face's entrance. |
| onSelect | (avatar: AvatarData, index: number) => void | — | Called when a face is clicked or activated with the keyboard. |
| autoplay | boolean | false | Sweeps a virtual pointer across the stack until someone points at it. |
Add it to your project
- 1
Set up your project once
You need a Next.js project with Tailwind CSS and the
@/import alias. In its root folder, run this once. It createscomponents.jsonand thecn()helper insrc/lib/utils.ts:npx shadcn@latest init -d
Starting from nothing? The Quick Start walks through the whole thing.
- 2
Connect the registry
Run this once per project. It writes the Nexus UI entry into
components.jsonfor you:npx shadcn@latest registry add "@nexus-labs=https://www.nexus-ui.com/api/registry/{name}"Type it exactly as shown.
{name}is filled in by the CLI with the component you ask for, so you never replace it.
- 3
Add the component
Run this from your project root. It adds the component, the helpers it imports and its npm packages.
npx shadcn@latest add @nexus-labs/avatar-group
- 4
Check what was added
With a project made as in the Quick Start (a
src/folder), these files land in it:components/avatar-group/avatar-group.tsxindex.ts - 5
Copying by hand? Skip the registry
Instead of steps 2 and 3 you can copy the files yourself, with no registry and no API key. Step 1 still applies, so that
cn()exists. Install the packages:npm install framer-motion
Then show the source and create each file at the path it gives:
- 6
Use it in a page
Installing only adds the files. Import the component in a page and render it. The Usage tab on the preview shows a fuller example with props:
// src/app/page.tsx import { AvatarGroup, type AvatarData } from "@/components/avatar-group"; export default function Page() { return ( <main> <AvatarGroup /> </main> ); }
Like Avatar Group? 256 more are in Pro.
Pro unlocks all 256 Pro components, every template and block, and everything we release next. Avatar Group stays free.
About Avatar Group
Avatar Group renders a horizontally overlapping stack of user avatars with per-avatar entrance animations and hover effects powered by Framer Motion. Each avatar supports a photo via `src`, with automatic color-coded initials fallback when no image is provided. Name tooltips with enter/exit animations appear on hover. Four entrance animation styles — flip, slide, scale, and bounce — stagger across the group on mount, and four hover styles — scale, lift, rotate, and up — make the hovered avatar stand out from the stack. Use it for social proof strips, team sections, collaborator counts, and anywhere a list of people needs to be communicated compactly.
Good for
- Social proof strips on pricing and landing pages
- Team member and collaborator count displays
- Active user and community size indicators
- Comment and reaction participant lists
Avatar Group questions
How do I install the avatar group?
Run `npx shadcn@latest add @nexus-labs/avatar-group`. It adds the AvatarGroup component and installs framer-motion.
What data does each avatar take?
Pass `avatars` as `{ src?, alt?, fallback, tooltip?, bgColor? }`. Without an image, or if the image fails to load, the `fallback` initials show on a colored circle, and `tooltip` sets the name shown on hover.
Which animations can I choose?
`entranceAnimation` takes "none", "fade", "flip", "slide", "scale" or "bounce", staggered by `entranceStagger`. `hoverAnimation` takes "scale", "lift", "rotate", "up" or "none", with `hoverScale` for the zoom.
How do I adjust size and spacing?
`size` sets the diameter in px (default 40), `overlap` sets how far avatars overlap (default 10), and `borderWidth`/`borderColor` style the ring. With reduced motion on, the entrance and hover animations are turned off.