Avatar Stack

A row of overlapping faces — the "people who…" cue under a headline, beside a count, or next to a join button. It shows up to 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.

Several sections used to hand-roll this row; Fashion Hero uses this one.

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.
showTooltiptrue: determines whether the gliding tooltip is displayed on hover; set to false to hide tooltips.
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 @avara-ui registry once, then copy your styles from the Themes page.

Install Avatar Stack

npx shadcn@latest add https://avaraui.com/r/avatar-stack.json

components/custom/blocks/AvatarStackBlock.tsx 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.

npx shadcn@latest add https://avaraui.com/r/tooltip.json https://avaraui.com/r/ui-avatar.json

@radix-ui/react-avatar and motion are npm packages.

npm install @radix-ui/react-avatar motion

Examples

A clean row of overlapping faces. Hovering expands the stack smoothly without displaying tooltips.

showTooltipfalse: disables the hover tooltip completely so the avatars fan out without displaying name or info popups.
spreadOnHover: slides each face a few pixels further than the one before it while the row is hovered; set it to false for 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; false keeps the stacking order fixed.

Hovering an avatar displays its name in a tooltip and zooms the face upward, keeping the row's gap fixed.

showTooltiptrue: displays the avatar's alt name in a floating tooltip on hover.
liftOnHovertrue: raises and zooms the hovered avatar above its neighbours.
spreadOnHoverfalse: keeps the spacing between avatars fixed so the gap does not expand.

Displays an anchored pointer arrow underneath the tooltip card with a lively spring popup animation as avatars smoothly zoom on hover.

showTooltiptrue: displays the avatar's alt name in a floating tooltip on hover.
showTooltipArrowtrue: renders a pointer arrow anchoring to the top of the avatar circle.
liftOnHovertrue: raises and zooms the hovered avatar above its neighbours.
spreadOnHoverfalse: keeps the spacing between avatars fixed so the gap does not expand.

Spread on hover (Expand width)

Hovering over the stack smoothly fans the avatars out to the right, widening the gap without zooming individual faces.

spreadOnHovertrue: smoothly shifts subsequent avatars to the right on hover, widening the stack.
spreadDistance6: sets the subtle shift distance in pixels per avatar (default is 6px).
transitionDuration500: controls the transition speed in milliseconds (default is 500ms for a gentle, smooth spread).
translate"-30%": subtly shifts the hovered avatar upward by -30% without flying high.
liftOnHoverfalse: disables zooming so the faces remain at their original scale.

Hovering over the stack widens the avatar gap to the right, elevates the hovered face by -30%, and displays a clean floating tooltip above it.

spreadOnHovertrue: smoothly shifts subsequent avatars to the right on hover, widening the stack.
spreadDistance6: sets the shift distance in pixels per avatar.
translate"-30%": subtly shifts the hovered avatar upward by -30%.
showTooltiptrue: displays a floating tooltip with the avatar's name on hover.
showTooltipArrowfalse: renders a clean tooltip without a pointer arrow.
liftOnHoverfalse: keeps the avatars at original scale without zooming.

Hovering widens the stack to the right, subtly raises the hovered face, and reveals a spring popup tooltip with an anchored pointer arrow.

spreadOnHovertrue: smoothly shifts subsequent avatars to the right on hover, widening the stack.
spreadDistance6: sets the shift distance in pixels per avatar.
translate"-30%": subtly shifts the hovered avatar upward by -30%.
showTooltiptrue: displays a floating tooltip on hover.
showTooltipArrowtrue: renders an anchored pointer arrow underneath with spring popup animation.
liftOnHoverfalse: keeps the avatars at original scale without zooming.

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-full and 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 false for 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; false keeps the stacking order fixed.

Folded count

Six people, three shown — the rest become a +3 disc. Hovering faces or the counter disc displays arrow tooltips.

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.
showTooltipArrowtrue: displays tooltips with pointer arrows and lively pop animations on hover.

Sizes

sm, md and lg — 28, 36 and 44 pixels. The middle stack shows without tooltip (showTooltip={false}), while the large stack displays tooltips with pointing arrows (showTooltipArrow={true}).

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.
showTooltipArrowtrue: renders a pointer arrow anchoring to the top of the avatar circle (as shown on the large stack).
ringClassName: is the gap colour between faces (ring-background by default). Match it to the surface the stack sits on.

Best Practices & Guidelines

Optimal Avatar Count

Limit visible avatars to 3–5 items using the max prop. Folding excess avatars into a +N counter keeps your layout balanced, avoids horizontal overflow on mobile screens, and maintains clean visual hierarchy.

Smooth Hover Motion

When enabling spreadOnHover, keep spreadDistance subtle (4–8px) and transitionDuration around 500ms. Pair with translate="-30%" to gently elevate the hovered avatar above its neighbors without jarring layout shifts.

Tooltip Accessibility & Text Alignment

Always provide accessible alt or name attributes for every avatar. When a designation or subtitle is provided, tooltips automatically align text to the left; otherwise, titles stay cleanly centered for single-line labels.

Ring Contrast & Background Matching

Ensure ringClassName matches the surface the avatars rest upon (defaults to ring-background). A matching border ring creates clean visual separation between overlapping faces in both light and dark modes.

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.
`showTooltip`	`boolean`	`true`	Whether to show the floating gliding tooltip on hover. Set to `false` to disable tooltips.
`children`	`ReactNode`	—	Composable `<Avatar>` elements containing images, fallbacks, and optional `<AvatarGroupTooltip>`.

AvatarStack Props

Prop	Type	Default	Description
`avatars`	`{ src: string; alt?: string; name?: string; tooltip?: string; designation?: string; role?: string; fallback?: string }[]`	Required	The list of faces in order. Hover tooltips display the avatar's name/alt, and optionally `designation`/`role` beneath it if provided.
`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.
`spreadDistance`	`number`	`6`	Number of pixels each subsequent avatar shifts to the right on hover when `spreadOnHover` is enabled.
`translate`	`string \| number`	`"-30%"`	Vertical displacement of an avatar when hovered (e.g. `"-30%"`).
`transitionDuration`	`number`	`500`	Duration of the spread and hover transition in milliseconds for a smooth, gentle animation.
`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`).
`showTooltipArrow`	`boolean`	`false`	Whether to render an anchored pointer arrow beneath the hover tooltip.