AvatarGroup

JLPNSI+1

Show codeHide code

<AvatarGroup
items={[
  { name: 'Jordan Lee', src: 'https://i.pravatar.cc/80?img=12' },
  { name: 'Priya Nair' },
  { name: 'Sam Ito', src: 'https://i.pravatar.cc/80?img=5' },
  { name: 'Casey Wren' },
]}
max={3}
/>

Add

npx @ava-ui/apogee add avatar-group

Pulls in Avatar.

Usage

---
import AvatarGroup from '@/components/apogee/AvatarGroup/AvatarGroup.astro'
---
<AvatarGroup items={[{ name: 'Jordan Lee' }, { name: 'Priya Nair' }]} max={5} />

Anatomy

• items mode — pass an items array; AvatarGroup renders an Avatar per entry (each gets the group’s size) plus a +N overflow chip when items.length > max.
• Manual mode — omit items and drop <Avatar> children into the default slot instead; you control each avatar’s props (including its own size). The overlap (-space-x-2) and ring (ring-2 ring-page) styling apply either way.

API

@composable — exposed to Content Editors in AVA. Any other native <div> attribute passes through.

Sizes

<AvatarGroup size="xsmall" items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
<AvatarGroup size="small" items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
<AvatarGroup items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
<AvatarGroup size="large" items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
<AvatarGroup size="xlarge" items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />

States

With overflow (items.length > max) vs. without (max omitted or ≥ items.length):

<AvatarGroup items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }, { name: 'G H' }]} max={2} />
<AvatarGroup items={[{ name: 'A B' }, { name: 'C D' }]} />

Examples

Manual composition — mixed sizes or custom per-avatar props aren’t possible via items:

JLPN

Show codeHide code

<AvatarGroup>
<Avatar name="Jordan Lee" src="https://i.pravatar.cc/80?img=12" />
<Avatar name="Priya Nair" />
</AvatarGroup>

Accessibility

• Each Avatar carries its own accessible name (image alt or the initials fallback’s aria-label) — see Avatar.
• The +N overflow chip is plain visible text (e.g. “+3”), not a control — it’s not focusable and doesn’t disclose the hidden names. If the overflow count needs to be actionable (e.g. open a full list), wrap the group in a <button> yourself; AvatarGroup doesn’t do this.

Tokens

Do / Don’t

• Do set max for groups that could grow unbounded (team members, watchers).
• Do keep size consistent within a group.
• Don’t mix items and slotted children — items (when set) takes over the default slot entirely.
• Don’t expect the +N chip to be interactive — it’s static text.

Content

• No component-specific copy — the overflow chip’s “+N” is generated, not authored.