Data Display

AvatarGroup

Overlapping collaborator avatar stack built on the Avatar primitive with focusable names and overflow count.

import { AvatarGroup } from '@lostgradient/cinder/avatar-group';
identitycollaboration
01

Overview

Overlapping collaborator stack built on Avatar, with focusable names and an overflow count.

Usage

svelte 
<script lang="ts">
  import AvatarGroup from '@lostgradient/cinder/avatar-group';
</script>

<AvatarGroup avatars={[{ name: 'Ada Lovelace' }, { name: 'Grace Hopper' }]} />
Live preview
02

When to use

Use when
  • Showing who is present, assigned, or collaborating in a compact surface.
  • Summarizing a bounded set of people with a visible overflow count.
Avoid when
  • Rendering a single person — use avatar instead.
  • Showing status, counts, or metadata labels unrelated to people — use badge, chip, or status-dot instead.
03

Examples

Collaborator stack

A compact stack of visible collaborators with focusable names.

Overflow count

Limit visible avatars and summarize hidden collaborators with a count.

Overlap and order

Customize overlap amount, shape, size, and visible stacking order.

04

Props

Props for avatar-group
Name Type Default Required Bindable Description
avatars AvatarGroupItem[] [] Collaborators to render in the stack.
maxVisible number Maximum visible avatars before overflow.
overlap text '0.75rem' Non-negative CSS length token for the amount each item overlaps its predecessor.
zOrder 'first-on-top' | 'last-on-top' 'last-on-top' Stacking order for visible avatars.
size 'xs''sm''md''lg''xl' 'md' Size token forwarded to each visible Avatar.
shape 'circle' | 'square' 'circle' Shape forwarded to each visible Avatar.
overflowLabel text Accessible label for the overflow indicator.
label text 'Collaborators' Accessible name for the avatar stack list.
style unknown req