Avatar Group

Display a group of avatars with optional overflow indicator and plus button

Avatar Group

Display multiple avatars in a group with overlapping layout and optional overflow indicator.

Usage

import { AvatarGroup, Avatar, AvatarImage } from "@/components/ui/avatar-group";

export default function Example() {
  return (
    <AvatarGroup variant="overlapping" max={3} showPlus>
      <Avatar>
        <AvatarImage src="/images/avatar-1.png" alt="User 1" />
      </Avatar>
      <Avatar>
        <AvatarImage src="/images/avatar-2.png" alt="User 2" />
      </Avatar>
      <Avatar>
        <AvatarImage src="/images/avatar-3.png" alt="User 3" />
      </Avatar>
      <Avatar>
        <AvatarImage src="/images/avatar-4.png" alt="User 4" />
      </Avatar>
    </AvatarGroup>
  );
}

Components

AvatarGroup

The container component that manages layout and overflow.

Avatar

Individual avatar wrapper with border and shadow styling.

AvatarImage

The image element inside an avatar.

AvatarFallback

Fallback content when image is unavailable.

AvatarGroupPlus

The plus button shown at the end of the group.

Props

AvatarGroup Props

Prop	Type	Default	Description
variant	"default" | "overlapping"	"default"	Layout variant - default has gap, overlapping uses negative margin
size	"sm" | "default" | "lg"	"default"	Size of avatars in the group
max	number	-	Maximum avatars to show before plus indicator
showPlus	boolean	false	Always show plus button even without overflow

Avatar Props

Prop	Type	Default	Description
size	"sm" | "default" | "lg"	"default"	Size of the avatar

AvatarGroupPlus Props

Prop	Type	Default	Description
count	number	-	Number to display (shows "+N")

Variants

Layout Variants

// Default - with gap
<AvatarGroup variant="default">
  <Avatar><AvatarImage src="..." /></Avatar>
  <Avatar><AvatarImage src="..." /></Avatar>
</AvatarGroup>

// Overlapping - negative margin
<AvatarGroup variant="overlapping">
  <Avatar><AvatarImage src="..." /></Avatar>
  <Avatar><AvatarImage src="..." /></Avatar>
</AvatarGroup>

Size Variants

// Small - 40px
<AvatarGroup size="sm">...</AvatarGroup>

// Default - 60px
<AvatarGroup size="default">...</AvatarGroup>

// Large - 80px
<AvatarGroup size="lg">...</AvatarGroup>

Examples

With Max Limit

<AvatarGroup variant="overlapping" max={3}>
  <Avatar><AvatarImage src="/avatar-1.png" /></Avatar>
  <Avatar><AvatarImage src="/avatar-2.png" /></Avatar>
  <Avatar><AvatarImage src="/avatar-3.png" /></Avatar>
  <Avatar><AvatarImage src="/avatar-4.png" /></Avatar>
  <Avatar><AvatarImage src="/avatar-5.png" /></Avatar>
</AvatarGroup>
// Shows 3 avatars + "+2" indicator

With Fallback

<Avatar>
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Always Show Plus

<AvatarGroup variant="overlapping" showPlus>
  <Avatar><AvatarImage src="/avatar-1.png" /></Avatar>
  <Avatar><AvatarImage src="/avatar-2.png" /></Avatar>
</AvatarGroup>
// Shows avatars + "+" button for adding more

Design Tokens

• Border: 1.5px solid var(--neutral-2-40)
• Border Radius: 16px (default), 12px (sm), 20px (lg)
• Shadow: 0px 24px 24px -8px rgba(0, 0, 0, 0.3)
• Plus Shadow: 0px 32px 24px -16px rgba(0, 0, 0, 0.4)
• Plus Blur: 6px

Found In

• Bento10 - Collaboration grid with avatar group
• Bento14 - Single avatar display
• Bento21 - Team collaboration pattern