Fumadocs on TanStack Start

Display a collection of overlapping avatars with overflow handling and interactive popover

Overview

The AvatarGroup component displays a collection of avatars in an overlapping layout with smart overflow handling. When the number of avatars exceeds the maximum, it shows a "+N" indicator with a popover containing all overflow avatars. Each avatar includes an individual tooltip on hover.

Import

import { AvatarGroup } from "@px-ui/core";

Usage

const avatars = [
  { name: "Alice Johnson", imgSrc: "https://github.com/shadcn.png", size: "40px" },
  { name: "Bob Smith", imgSrc: null, size: "40px" },
  { name: "Carol Williams", imgSrc: null, size: "40px" },
  { name: "David Brown", imgSrc: null, size: "40px" },
];

<AvatarGroup avatars={avatars} />

Examples

With Overflow

When there are more avatars than the max prop allows, the component shows a "+N" indicator. Hover over it to see all overflow avatars in a popover.

Max 4 avatars (hover +N to see all)

Max 6 avatars

const avatars = [
  { name: "Alice Johnson", imgSrc: null, size: "40px", variant: "rounded" },
  { name: "Bob Smith", imgSrc: null, size: "40px", variant: "rounded" },
  // ... 6 more avatars
];

<AvatarGroup avatars={avatars} max={4} />
<AvatarGroup avatars={avatars} max={6} />

Different Sizes

The AvatarGroup automatically adapts to the size specified in the avatar props, maintaining proper overlap and scaling.

Small (32px)

Default (40px)

Large (48px)

const smallAvatars = [
  { name: "Alice Johnson", imgSrc: null, size: "32px", variant: "rounded" },
  { name: "Bob Smith", imgSrc: null, size: "32px", variant: "rounded" },
  // ...
];

const largeAvatars = [
  { name: "Alice Johnson", imgSrc: null, size: "48px", variant: "rounded" },
  { name: "Bob Smith", imgSrc: null, size: "48px", variant: "rounded" },
  // ...
];

<AvatarGroup avatars={smallAvatars} />
<AvatarGroup avatars={largeAvatars} />

API Reference

AvatarGroup

A component that displays a collection of overlapping avatars with overflow handling.

Prop	Type	Default	Description
`avatars`	`Array<ComponentProps<typeof Avatar>>`	-	Array of avatar configurations. Each item should be a valid Avatar component props object
`max`	`number`	`4`	Maximum number of avatars to display before showing overflow indicator
`className`	`string`	-	Additional CSS classes for the container

Avatar Props

Each object in the avatars array accepts all Avatar component props:

Prop	Type	Description
`name`	`string`	User name for initials fallback and tooltip
`imgSrc`	`string \| null`	Image source URL
`size`	`${number}px`	Size of the avatar (e.g., "40px", "48px")
`variant`	`"squared" \| "rounded"`	Visual style variant

Features:

Avatars overlap by 25% of their width for a compact layout
Each avatar has a white ring border to separate them visually
Z-index stacking ensures proper depth (first avatar appears on top)
Overflow avatars are shown in a scrollable popover on hover
Individual tooltips show each user's name on hover

AvatarGroup

On this page