AvatarGroup

Import

import { AvatarGroup } from '@delightstack/components';

Basic Usage

A

B

C

View code

<script>
  import { AvatarGroup } from '@delightstack/components';

  const members = [
    { name: 'Alice', src: '/avatars/alice.jpg' },
    { name: 'Bob', src: '/avatars/bob.jpg' },
    { name: 'Charlie', src: '/avatars/charlie.jpg' },
  ];
</script>

<AvatarGroup avatars={members} />

Examples

Limiting Visible Avatars

When the number of avatars exceeds max, a “+N” overflow indicator appears.

<script>
  const team = [
    { name: 'Alice', src: '/avatars/alice.jpg' },
    { name: 'Bob', src: '/avatars/bob.jpg' },
    { name: 'Charlie', src: '/avatars/charlie.jpg' },
    { name: 'Diana', src: '/avatars/diana.jpg' },
    { name: 'Eve', src: '/avatars/eve.jpg' },
    { name: 'Frank', src: '/avatars/frank.jpg' },
  ];
</script>

<AvatarGroup avatars={team} max={3} />

Different Sizes

A

B

C

D

A

B

C

D

A

B

C

D

View code

<AvatarGroup avatars={team} size="0" max={4} />
<AvatarGroup avatars={team} size="2" max={4} />
<AvatarGroup avatars={team} size="3" max={4} />

Expandable Overflow

When expandable is true, clicking the overflow indicator reveals all hidden avatars.

AJ

BS

CB

+3

View code

<AvatarGroup
avatars={team}
max={3}
expandable
/>

Clickable Avatars

AJ

BS

CB

DP

View code

<AvatarGroup
avatars={team}
onclick={({ avatar, index }) => openProfile(avatar)}
/>

With Overflow Click Handler

AJ

BS

CB

+3

View code

<AvatarGroup
avatars={team}
max={3}
onoverflowclick={({ remaining }) => showAllParticipants(remaining)}
/>

Skeleton Loading

Show loaded

View code

<AvatarGroup skeleton={loading} skeleton_count={4} avatars={loading ? [] : members} />

Props

Prop	Type	Default	Description
avatars	AvatarData[]	[]	Array of avatar data
max	number	5	Maximum visible avatars before overflow
size	'0' | '1' | '2' | '3' | '4' | '5'	'1'	Avatar size (passed to each Avatar)
overlap	number	0.25	Overlap ratio (0-1)
direction	'left' | 'right'	'right'	Stack direction
ring_color	string	'var(--color-bg)'	Ring/border color around each avatar
expandable	boolean	false	Click overflow to reveal all
skeleton	boolean	false	Show loading skeleton
skeleton_count	number	4	Number of skeleton circles to show
id	string	auto	Element ID
class	string	''	Additional CSS classes

Events

Event	Detail	Description
onclick	{ avatar: AvatarData, index: number }	Individual avatar clicked
onoverflowclick	{ remaining: AvatarData[] }	Overflow “+N” indicator clicked

Types

interface AvatarData {
  src?: string;
  name: string;
  href?: string;
}

Accessibility

• Container has role="group" with aria-label="Avatar group"
• Each avatar has an accessible name from the name field in AvatarData
• Tooltips display each avatar’s name on hover
• Overflow indicator has aria-label (e.g., “3 more avatars”)
• When expandable or onoverflowclick is set, the overflow indicator has role="button" and is keyboard accessible (Enter/Space)
• Hovered avatar rises slightly with translateY(-2px) for visual feedback