Avatar Group

An animated avatar group that displays overlapping user images and smoothly shifts each avatar forward on hover to highlight it.

Powered by

Motion

Installation

npx shadcn@latest add @redpanda/avatar-group

pnpm dlx shadcn@latest add @redpanda/avatar-group

yarn dlx shadcn@latest add @redpanda/avatar-group

bunx shadcn@latest add @redpanda/avatar-group

nubx shadcn@latest add @redpanda/avatar-group

aube dlx shadcn@latest add @redpanda/avatar-group

AvatarGroup

An animated avatar group built with TailwindCSS and Motion, where avatars gently shift forward on hover to highlight each user.

Installation

Usage

const people = [  {    id: 'user-ben',    src: 'https://avatars.githubusercontent.com/u/9860550?v=4',    name: 'Beniamin Malinski',    initials: 'BM',  },  {    id: 'user-blair',    src: 'https://avatars.githubusercontent.com/u/23467862?v=4',    name: 'Blair McKee',    initials: 'BM',  },];
<AvatarGroup  items={people.map((person) => ({    id: person.id,    content: (      <Avatar>        <AvatarImage alt={person.name} src={person.src} />        <AvatarFallback>{person.initials}</AvatarFallback>        <AvatarGroupTooltip>{person.name}</AvatarGroupTooltip>      </Avatar>    ),  }))}/>;

Use overlap="tight" for the shared compact-overlap recipe and Avatar frame="group" for the owned separator around each overlapping image. Keep avatar dimensions explicit; no local negative-spacing or border paint is needed. This animated AvatarGroup is separate from the static AvatarGroup exported by avatar; its item API and motion/tooltip behavior are unchanged.

Each item requires a nonempty, unique domain id and one React element in content. IDs survive insertion, removal, and reordering; do not derive them from an array index or mutable display text. Changing an ID deliberately starts a new mounted item. JSX children are no longer accepted.

When to use

Use AvatarGroup to display multiple users in a compact, visually appealing way with interactive hover effects:

Use AvatarGroup when:

• Showing team members or project collaborators
• Displaying recent activity participants
• Building user lists with limited space
• Creating interactive user showcases
• Indicating multiple users in shared contexts

Don’t use AvatarGroup when:

• Showing a single user (use Avatar instead)
• Building full user directories (use a proper list layout)
• Displaying users that don’t have relationships
• The avatars don’t need overlapping or hover effects

Anatomy

The AvatarGroup component creates an overlapping layout with interactive hover animations:

AvatarGroup Container┌─────────────────────────────────────────────────────────────────┐│ TooltipProvider (hover delay management)                       ││ ┌─────────────────────────────────────────────────────────────┐ ││ │ Group Container (flex, -space-x-2)                         │ ││ │ ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐                     │ ││ │ │Avatar│  │Avatar│  │Avatar│  │Avatar│                     │ ││ │ │  1   │  │  2   │  │  3   │  │  4   │                     │ ││ │ │z-1   │  │z-2   │  │z-3   │  │z-4   │                     │ ││ │ └──────┘  └──────┘  └──────┘  └──────┘                     │ ││ │     ↑         ↑         ↑         ↑                        │ ││ │   On hover: translates up (-30% by default)                │ ││ └─────────────────────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────────────┘
Hover Behavior:- Mouse enters avatar → Avatar moves up with spring animation- Tooltip appears above the moved avatar- Mouse leaves → Avatar returns to original position- Tooltip disappears

Component Hierarchy:

1. AvatarGroup (Root): Container managing layout and animation settings
2. TooltipProvider: Manages tooltip delay and interactions
3. AvatarContainer: Individual wrapper for each avatar with hover logic
4. Avatar: The actual avatar component (image + fallback)
5. AvatarGroupTooltip: Tooltip content shown on hover

Key Features:

• Overlapping Layout: Uses negative margin (-space-x-2) for overlap
• Z-Index Management: Each avatar has increasing z-index for proper stacking
• Hover Animation: Spring-based upward translation on hover
• Tooltip Integration: Built-in tooltip system with customizable content
• Responsive: Adapts to different avatar sizes

Animation Properties:

• Default Transition: Spring animation (stiffness: 400, damping: 30)
• Default Translate: -30% upward movement
• Hover States: Smooth enter/exit animations
• Touch Support: The motion treatment responds to tap. Keep user names available through avatar image alt text; the visual tooltip is supplementary.
• Feature ownership: The group supplies its own synchronous, non-strict LazyMotion animation features. No app-level provider is required; item content can still use full Motion components.

Examples

Bottom translation

Props

AvatarGroup

AvatarGroupTooltip

Credits

• We use Animate UI from imskyleen for all the animations.