Avatar Stack
max faces, folds the rest into a "+N" disc, and takes an optional trailing action that shares the stack's size. On hover the faces fan apart a little, so the row answers the pointer without turning into a carousel.Avatar Group (Shift on hover)
An animated avatar group inspired by animate-ui that displays overlapping user images and smoothly shifts each avatar upward with spring physics on hover with an anchored pointer tooltip.
translate"-30%"- controls the upward vertical displacement when hovered (default is -30%).
invertOverlaptrue- layers earlier avatars over later avatars, while elevating the currently hovered avatar to z-index 50.
AvatarGroupTooltip- anchors a floating pointer tooltip above the shifted face with smooth spring entrance and exit.
Installation
New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.
Install Avatar Stack
components/ is written into your project. Copy any snippet from a Usage tab above and it runs.
Install dependencies
Step 1 installs these for you. Run them yourself only if you are adding Avatar Stack to an existing project by hand. The cn helper and lucide-react are not listed — the installation guide covers them once for every component.
tooltip and ui-avatar are components, not packages — the shadcn CLI installs them as source files.
@radix-ui/react-avatar and motion are npm packages.
Examples
Without tooltip
A clean row of overlapping faces without displaying tooltips.
showTooltipfalse- disables the hover tooltip completely so the avatars fan out without displaying name or info popups.
With an action
Three faces and a plus button that shares their size. Hover the row and the faces fan out.
action- is any element rendered last in the row at the same size as a face — give it
size-fulland its own ring. A link or a button both work. spreadOnHover- slides each face a few pixels further than the one before it while the row is hovered; set it to
falsefor a still row. liftOnHover- raises the face under the pointer above its neighbours and grows it a touch, so a half-covered face can be seen whole;
falsekeeps the stacking order fixed.
Folded count
Six people, three shown — the rest become a +3 disc.
max- is how many faces show before the rest fold into a count. The count disc is black, so it reads as a number, not a face.
Sizes
sm, md and lg — 28, 36 and 44 pixels. The middle stack shows without tooltip (showTooltip={false}), while the others display tooltips on hover.
size- controls the avatar circle dimensions: sm (28px), md (36px), lg (44px), or xl (48px).
showTooltipfalse- can be disabled individually per stack (as shown on the middle stack) or left enabled.
ringClassName- is the gap colour between faces (
ring-backgroundby default). Match it to the surface the stack sits on.
Props Reference
AvatarGroup Props
| Prop | Type | Default | Description |
|---|---|---|---|
translate | string | number | "-30%" | Vertical displacement of each avatar on hover using spring motion. |
invertOverlap | boolean | true | Whether earlier avatars sit on top of subsequent ones. Hovering automatically raises an avatar's z-index to 50. |
transition | Transition | { type: "spring", stiffness: 300, damping: 17 } | Spring transition configuration for the hover shift animation. |
children | ReactNode | — | Composable <Avatar> elements containing images, fallbacks, and optional <AvatarGroupTooltip>. |
AvatarStack Props
| Prop | Type | Default | Description |
|---|---|---|---|
avatars | { src: string; alt?: string; tooltip?: string; fallback?: string }[] | Required | The list of faces in order. The alt or tooltip text is displayed inside the hover tooltip. |
variant | "default" | "shift" | "default" | Presentation style: default (smooth fan out) or shift (animate-ui spring shift upward with pointer tooltip). |
size | "sm" | "md" | "lg" | "xl" | "md" | Avatar diameter: sm (28px), md (36px), lg (44px), or xl (48px). |
max | number | 4 | Maximum faces shown before the rest fold into a +N count disc. |
ringClassName | string | "ring-background" | Border/gap colour between overlapping faces. Defaults to theme background. |
action | ReactNode | — | A trailing element (such as an add/join button) rendered at the same size as an avatar. |
spreadOnHover | boolean | true | Whether faces smoothly fan apart slightly when the stack is hovered. |
liftOnHover | boolean | true | Whether the hovered face rises above neighbours and scales up slightly. |
showTooltip | boolean | true | Whether hover reveals the avatar's alt text in a tooltip. Set to false to disable tooltips. (Alias: tooltip). |