Avatar Group

Powered by

Animate UIMotion

AvatarGroup

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

Installation

Usage

<AvatarGroup>
  {AVATARS.map((avatar, index) => (
    <Avatar key={index}>
      <AvatarImage src={avatar.src} />
      <AvatarFallback>{avatar.fallback}</AvatarFallback>
      <AvatarGroupTooltip>
        <p>{avatar.tooltip}</p>
      </AvatarGroupTooltip>
    </Avatar>
  ))}
</AvatarGroup>

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: Works on mobile with tap events

Examples

Bottom translation

Props

AvatarGroup

AvatarGroupTooltip

Credits

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