AvatarGroup

<AvatarGroup>TailwindCSS Modules

Displays multiple avatars stacked together horizontally. Used for showing multiple contributors, active viewers, or group membership, with automatic +N overflow bubbling.

InstallationColoxo CLI
npx coloxo add avatar-group --style coloxo-css
ES Module ImportPlayground / npm package
import { AvatarGroup } from '@coloxo/ui';

Design Tokens:

--cx-bg-primary: #FFFFFF--cx-slate-200: #E2E8F0--cx-radius-full: 9999pxring: 2px solid white

1. Variant Matrix

Different combinations of AvatarGroups using images, initials, and overflow limits.

Images (Max 3)Initials (Max 4)No Overflow (Max 10)With Border
Group
User 1User 2User 3+4
+1
User 1User 2User 3
User 1User 2User 3+4

2. Control heights (Sizes)

The AvatarGroup inherits the same 6 standard sizes as the standalone Avatar component.

Sizes

size="xs"
Dimensions: 24px (1.5rem)
User 1User 2User 3+4

Dense tables, inline avatars

size="sm"
Dimensions: 32px (2rem)
User 1User 2User 3+4

Secondary lists, compact toolbars

size="md"DEFAULT
Dimensions: 40px (2.5rem)
User 1User 2User 3+4

Standard forms, page headers

size="lg"
Dimensions: 48px (3rem)
User 1User 2User 3+4

Hero sections, primary cards

3. Interactive Props Configurator

Use Initials

border

Visual Render CanvasHEIGHT: 40PX
User 1User 2User 3User 4+2
tsx
<AvatarGroup  max={4}  items={[    { src: "https://i.pravatar.cc/150?u=a042581f4e29026704a" },    { src: "https://i.pravatar.cc/150?u=a042581f4e29026704b" },    { src: "https://i.pravatar.cc/150?u=a042581f4e29026704c" },    { src: "https://i.pravatar.cc/150?u=a042581f4e29026704d" },    { src: "https://i.pravatar.cc/150?u=a042581f4e29026704e" },    { src: "https://i.pravatar.cc/150?u=a042581f4e29026704f" }  ]}/>

4. Dark theme

AvatarGroups automatically update their stack ring shadow color to match dark mode backgrounds.

User 1User 2User 3User 4+3
+2

5. Enterprise layout compositions

AvatarGroups are frequently used in task headers, active user indicators, and comment threads.

Project Alpha

Active Contributors

User 1User 2User 3User 4+3

Accessibility

Grouping Role

The root div uses role='group' to announce the collection of avatars together.

Overflow Label

The overflow bubble uses an aria-label (e.g., '3 more') to ensure screen readers announce the numeric summary instead of just '+3'.

Alt Text

Always provide 'alt' text in the items array for image avatars to ensure users know who is present in the group.

Props

NameTypeDefaultDescription
itemsAvatarGroupItem[]—Avatar entries.
maxnumber5Visible avatars before +N.
size"xs" | "sm" | "md" | "lg" | "xl" | "2xl"mdAvatar size.