Avatar Stack

A row of overlapping circular avatars; on hover or focus the avatar lifts and scales up, its neighbours move aside, and a name tooltip floats out.

Loading preview…

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

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

Max items shownmax

Avatar size (px)size

<AvatarStack />

Installation

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

Or, once registries are configured in components.json, install it as @webberui/avatar-stack.

Usage

import { AvatarStack } from "@/components/ui/avatar-stack";

<AvatarStack
  avatars={[
    { src: "/team/ada.jpg", alt: "Ada Lovelace" },
    { alt: "Alan Turing" },
    { alt: "Grace Hopper", fallback: "GH" },
  ]}
  max={5}
  size={40}
/>;

Props

Prop	Type	Default	Description
`avatars`	`AvatarStackItem[]`	—	The avatars, stacked left to right in order (left on top of right)
`max`	`number`	`5`	How many avatars to show at most; the rest are collapsed into a +N bubble
`size`	`number`	`40`	Avatar diameter (px)
`className`	`string`	—	Custom styles for the outer container

AvatarStackItem

Field	Type	Description
`src`	`string?`	Avatar image URL; when omitted, the text fallback is shown
`alt`	`string`	Alternative text, also used as the name shown in the tooltip
`fallback`	`string?`	Character shown when there is no image; when omitted, the first character of `alt` is used

How it works

Avatars overlap via negative margins, with the left one on top of the right one (z-index decreases from left to right).
On hover or keyboard focus of any avatar, that avatar lifts and scales up and takes the topmost layer, its left and right neighbours move aside, and a name tooltip floats out above it.
With no image, a stable gradient background is generated from the name and the first character is shown; the same name always produces the same result.
Avatars beyond max are collapsed into a +N bubble that follows the visible avatars.

Accessibility

Each avatar is a button with an aria-label (the name), can be focused with Tab, and shows the tooltip on focus just as it does on hover.
The tooltip is purely visual (aria-hidden); the name is already exposed to assistive technology through aria-label, which avoids it being announced twice.
The +N bubble carries role="img" and an aria-label (such as 「還有 2 位成員」, "2 more members").
When the user has "reduce motion" enabled at the system level, the lift, the scale-up, and the offsetting are disabled; the tooltip still appears.