---
title: Avatar Group
description: An animated avatar group that displays overlapping user images and smoothly shifts each avatar forward on hover to highlight it.
icon: users
author:
  name: imskyleen
  url: https://github.com/imskyleen
mode: wide
---

<PoweredBy packages={[{ name: 'Motion', url: 'https://motion.dev/' }]} />

### Installation

```package-install
npx 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.

<ComponentPreview name="avatar-group-demo" />

### Installation

### Usage

```tsx
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:

```mermaid
graph TD;
    A[❓ Need to show multiple users?] --> B{How many users?};

    B -->|2-6 users| C[✅ Use AvatarGroup];
    B -->|1 user| D[⚠️ Use single Avatar];
    B -->|7+ users| E[⚠️ Consider AvatarGroup with count indicator];

    F{Users are team members?} -->|Yes| C;
    G{Users are contributors/collaborators?} -->|Yes| C;
    H{Need to show user relationships?} -->|Yes| C;

    I{Space is limited?} -->|Yes| J[✅ Use AvatarGroup with smaller avatars];
    I -->|No| K[ℹ️ Use regular Avatar list];

    L{Need interactive tooltips?} -->|Yes| M[✅ Use AvatarGroup with AvatarGroupTooltip];
    L -->|No| N[✅ Use plain AvatarGroup];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class C,J,M,N recommended;
    class D,E discouraged;
    class A,B,F,G,H,I,L decision;
    class K neutral;
```

**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

<ComponentPreview name="avatar-group-bottom-demo" />

### Props

#### AvatarGroup

| Prop | Type | Default | Description |
| - | - | - | - |
| `items` | `readonly AvatarGroupItem[]` | - | Ordered items with unique stable IDs and avatar element content |
| `overlap?` | `'standard' \| 'tight'` | `standard` | Standard 8px overlap or tight 12px overlap for the overlapping identity row |
| `className?` | `string` | - | The className of the avatar group |
| `transition?` | `Transition` | `{ type: 'spring', stiffness: 400, damping: 30 }` | The transition of the avatar group |
| `invertOverlap?` | `boolean` | `false` | By default, the avatar group is rendered in the same z-index as the avatars. This prop allows you to invert the z-index of the avatar group. |
| `translate?` | `string \| number` | `-30%` | The translate y of the avatar group |
| `tooltipProps?` | `Omit<TooltipContentProps, 'children'>` | `{ side: 'top', sideOffset: 24 }` | The props to pass to the tooltip |

#### AvatarGroupTooltip

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | - | The children of the avatar group tooltip |

## Credits

- We use [Animate UI](https://github.com/animate-ui/animate-ui) from [imskyleen](https://github.com/imskyleen) for all the animations.