AvatarGroup

InstallationCopy Anchor Link

npx vayu-ui-cli@latest add avatar-group

UsageCopy Anchor Link

PreviewCode

Avatar Group Examples

Basic Stack

JS

AJ

+2

Grid Layout (All Visible)

JS

AJ

DL

Sizes

JS

JS

JS

JS

Interactive (Click avatars to select)

JS

AJ

+1

With Overflow

JS

+3

Status Indicators

JS

AJ

AnatomyCopy Anchor Link

<AvatarGroup>
  {/* Root container — role="group" */}
  <AvatarItem>
    {/* Per-user avatar wrapper with Avatar inside */}
    <Avatar>
      <Avatar.Image />
      <Avatar.Status />
    </Avatar>
  </AvatarItem>
  <AvatarItem>...</AvatarItem>
  <OverflowButton>{/* "+N" indicator shown when users exceed maxDisplay */}</OverflowButton>
</AvatarGroup>

AccessibilityCopy Anchor Link

Keyboard SupportCopy Anchor Link

ARIA AttributesCopy Anchor Link

Focus BehaviorCopy Anchor Link

• Focus is managed via roving tabindex on interactive avatars (role="button")
• focus-visible ring uses ring-focus design token with offset
• All hover animations respect prefers-reduced-motion via motion-safe: prefix
• Minimum touch target of 24x24px (WCAG 2.5.5)

Screen reader behaviorCopy Anchor Link

A screen reader announces the group as "Avatar group with N members, list" followed by each avatar individually. Each avatar is announced using the username property (e.g., "John Doe's avatar, image"). Avatars without an image source fall back to the initials text. When the overflow button is present, it is announced as "Show N more users, button".

Component Folder StructureCopy Anchor Link

AvatarGroup/
├── AvatarGroup.tsx              # Composition — data processing + layout
├── AvatarItem.tsx               # Individual avatar wrapper with positioning
├── AvtarGroupOverflowButton.tsx # "+N more" overflow indicator
├── hooks.ts                     # Spacing calculation and keyboard navigation
├── types.ts                     # Type definitions
├── index.ts                     # Public API exports
└── README.md

PropsCopy Anchor Link

AvatarGroupCopy Anchor Link

UserDataCopy Anchor Link

Size ReferenceCopy Anchor Link

Spacing ReferenceCopy Anchor Link