Data Display

AvatarGroup

Display a collection of avatars in a stacked layout. Supports overflow truncation with a "+N" indicator, uniform sizing, and can be composed with children or an avatars prop.

Playground

Experiment with different props in real-time.

Size

Max

Basic Usage

Wrap Avatar components inside AvatarGroup to display them in a stacked layout.

<script lang="ts">
  import { Avatar, AvatarGroup } from 'sv5ui';
</script>

<AvatarGroup>
  <Avatar src="https://i.pravatar.cc/300?u=1" alt="User 1" />
  <Avatar src="https://i.pravatar.cc/300?u=2" alt="User 2" />
  <Avatar src="https://i.pravatar.cc/300?u=3" alt="User 3" />
</AvatarGroup>

With Max

Set the max prop to limit visible avatars. Overflow displays a "+N" indicator. Requires the avatars prop.

<AvatarGroup
  max={3}
  avatars={[
    { src: 'https://i.pravatar.cc/300?u=1', alt: 'User 1' },
    { src: 'https://i.pravatar.cc/300?u=2', alt: 'User 2' },
    { src: 'https://i.pravatar.cc/300?u=3', alt: 'User 3' },
    { src: 'https://i.pravatar.cc/300?u=4', alt: 'User 4' },
    { src: 'https://i.pravatar.cc/300?u=5', alt: 'User 5' },
    { src: 'https://i.pravatar.cc/300?u=6', alt: 'User 6' }
  ]}
/>

Sizes

The size prop controls the dimensions of all avatars in the group.

<AvatarGroup size="sm">
  <Avatar src="https://i.pravatar.cc/300?u=10" alt="User 1" />
  <Avatar src="https://i.pravatar.cc/300?u=11" alt="User 2" />
  <Avatar src="https://i.pravatar.cc/300?u=12" alt="User 3" />
</AvatarGroup>

<AvatarGroup size="md">
  <Avatar src="https://i.pravatar.cc/300?u=10" alt="User 1" />
  <Avatar src="https://i.pravatar.cc/300?u=11" alt="User 2" />
  <Avatar src="https://i.pravatar.cc/300?u=12" alt="User 3" />
</AvatarGroup>

<AvatarGroup size="lg">
  <Avatar src="https://i.pravatar.cc/300?u=10" alt="User 1" />
  <Avatar src="https://i.pravatar.cc/300?u=11" alt="User 2" />
  <Avatar src="https://i.pravatar.cc/300?u=12" alt="User 3" />
</AvatarGroup>

<AvatarGroup size="xl">
  <Avatar src="https://i.pravatar.cc/300?u=10" alt="User 1" />
  <Avatar src="https://i.pravatar.cc/300?u=11" alt="User 2" />
  <Avatar src="https://i.pravatar.cc/300?u=12" alt="User 3" />
</AvatarGroup>

Using Avatars Prop

Pass an array of AvatarProps to the avatars prop instead of using children.

<script lang="ts">
  import { AvatarGroup } from 'sv5ui';

  const users = [
    { src: 'https://i.pravatar.cc/300?u=20', alt: 'Alice' },
    { src: 'https://i.pravatar.cc/300?u=21', alt: 'Bob' },
    { src: 'https://i.pravatar.cc/300?u=22', alt: 'Charlie' },
    { src: 'https://i.pravatar.cc/300?u=23', alt: 'Diana' }
  ];
</script>

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

With Initials Fallback

Avatars without images fall back to initials using the text prop.

<AvatarGroup>
  <Avatar text="AB" alt="Alice Brown" />
  <Avatar text="CD" alt="Charlie Davis" />
  <Avatar src="https://i.pravatar.cc/300?u=30" alt="Eve" />
  <Avatar text="FG" alt="Frank Green" />
</AvatarGroup>

UI Slots

Use the ui prop to override classes on specific internal elements of the AvatarGroup.

Slot	Description
`root`	Outer container element — controls layout, spacing, and alignment of the avatar stack
`base`	Individual avatar wrapper — controls overlap, ring, and z-index of each avatar

Snippets

Name	Description
`children`	Custom children content — use when composing Avatar components manually instead of using the avatars prop

Props

Prop	Type	Default	Description
`as`	`keyof HTMLElementTagNameMap`	`'div'`	HTML element to render as
`size`	`'3xs' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`	`'md'`	Size applied to all avatars in the group
`avatars`	`AvatarProps[]`	`-`	Array of avatar props to render (alternative to children)
`max`	`number`	`-`	Maximum visible avatars; overflow shows a "+N" indicator
`class`	`string`	`-`	Additional CSS classes for root element
`ui`	`{ root, base }`	`-`	Override classes on internal elements

Avatar Badge