Avatar Stack

Overview

An overlapping avatar row that fans apart on hover with springy name tooltips.

This profile component is intended for interfaces that need an overlapping avatar row that fans apart on hover with springy name tooltips, account pages, and team directories. Its implementation is provided as editable source so the final behavior and styling stay inside your project.

Technologies

React

TypeScript

Tailwind CSS

Motion

Detected package dependencies: framer-motion.

@spectrumui/avatar-stack

Project team7 members · 3 online

Hover the stack — then hover a face

Installation

Usage

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

<AvatarStack
  items={[
    { name: "Arjun Mehta", src: "/avatars/01.png" },
    { name: "Priya Nair" },
    { name: "Noah Kim" },
  ]}
  onAvatarClick={(item) => console.log(item.name)}
/>

API Reference

AvatarStack

Renders a role="group" of avatar buttons with roving arrow-key focus; each item is an AvatarItem of shape { name: string; src?: string }. When src is omitted, initials are derived from the first two words of name. The name also becomes the button's aria-label and the tooltip text, and Escape collapses an expanded stack.

Prop	Type	Default	Description
*`items`	`AvatarItem[]`	-	People to render; the first max are visible, the rest sit behind the +N pill
`max`	`number`	`4`	Number of avatars shown before overflowing into the +N pill
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Avatar diameter: 28, 36 or 44px
`expandable`	`boolean`	`true`	Whether clicking the +N pill expands the hidden avatars with a stagger
`onAvatarClick`	`(item: AvatarItem, index: number) => void`	-	Fires when an avatar is clicked or activated with Enter/Space
`className`	`string`	-	Additional classes merged onto the group container

Examples

Sizes

expandable=false — the +2 pill stays put

Use cases

interfaces that need an overlapping avatar row that fans apart on hover with springy name tooltips
account pages
team directories

Features

Copy-paste source that remains in your repository
TypeScript source included with the component
Tailwind CSS classes editable in the component source
Animation implemented with Motion
Responsive Tailwind variants present in the source
Reduced-motion handling present in the source

Accessibility

The source includes ARIA attributes or roles; preserve them when customizing the component.
The source includes keyboard event handling; verify it alongside pointer behavior.
The source checks reduced-motion preferences or includes motion-reduce styles.
Test focus order, keyboard operation, labels, contrast, and screen-reader output in the final application context.

Customization

Edit the Tailwind utility classes in the copied source to match your spacing, color, and typography tokens.
Use the documented className surface for local layout adjustments, then edit the source for structural changes.
Adjust Motion transitions in the source and keep the reduced-motion behavior aligned with the final interaction.

Profile Dropdown

A user profile dropdown menu with avatar, settings, and logout actions.

Animated Card

A card that animates on hover to showcase tools, technologies, and features.

3D Event Badge

An interactive 3D event badge rendered with Three.js and React Three Fiber.

Card

A set of pre-designed cards for login, signup, pricing, and dashboards.

Topic guides

See how this component fits into broader interface patterns, implementation decisions, and working examples.

Animation Library AI UI Components

Avatar Stack FAQ

Is Avatar Stack free to use in commercial projects?

Yes. The public Avatar Stack source is available under the Apache License 2.0, including for commercial use, subject to the LICENSE terms.

How do I install Avatar Stack?

Run npx shadcn@latest add @spectrumui/avatar-stack. The page also exposes the source for manual installation.

Does Avatar Stack require Motion?

Yes. Motion usage was detected in the documented source or registry dependencies for Avatar Stack.

Does Avatar Stack use shadcn/ui or Radix UI?

No shadcn/ui or Radix UI dependency was detected in the documented Avatar Stack source.

Can I use Avatar Stack in Next.js?

The documented React source is used in this Next.js application. Keep its use client directive when copying it into the App Router. Install the detected dependencies and verify any application-specific data or image configuration.

What accessibility checks should I run for Avatar Stack?

The source includes ARIA markup, keyboard handlers, reduced-motion handling. Test the finished interface with keyboard and screen-reader workflows.