Components Data display
AvatarGroup
StableA stack of overlapping avatars with a "+N" overflow, announced as a list.
Use AvatarGroup to show who is involved, such as template editors, contract signers or team members, in limited space. Set max to collapse extra people into a counter, and total when the full list is not loaded.
Overview
import { Avatar, AvatarGroup } from '@bindshq/stance-react';
const people = [
'Amara Okafor',
'Lukas Novak',
'Priya Raman',
'Tomás Ferreira',
'Hana Sato',
'Oliver Grant',
];
export function Basic() {
return (
<AvatarGroup aria-label="Template editors">
{people.slice(0, 4).map((n) => (
<Avatar key={n} name={n} />
))}
</AvatarGroup>
);
}Light, dark and high contrast
Every Stance component is designed and tested in all three appearance modes.
Import
import { AvatarGroup, Avatar } from '@bindshq/stance-react';Platforms
AvatarGroup has native counterparts. They share Stance tokens and intent, and use each platform’s own controls and conventions. The live previews on this page are the web implementation.
import { AvatarGroup, Avatar } from '@bindshq/stance-react';Playground
<AvatarGroup />Examples
import { Avatar, AvatarGroup } from '@bindshq/stance-react';
const people = [
'Amara Okafor',
'Lukas Novak',
'Priya Raman',
'Tomás Ferreira',
'Hana Sato',
'Oliver Grant',
];
export function Overflow() {
return (
<AvatarGroup
aria-label="Sales team"
max={3}
total={48}
overflowLabel={(n) => `${n} more team members`}
>
{people.map((n) => (
<Avatar key={n} name={n} />
))}
</AvatarGroup>
);
}import { Avatar, AvatarGroup } from '@bindshq/stance-react';
const people = [
'Amara Okafor',
'Lukas Novak',
'Priya Raman',
'Tomás Ferreira',
'Hana Sato',
'Oliver Grant',
];
export function Sizes() {
return (
<div style={{ display: 'grid', gap: 16 }}>
{(['sm', 'md', 'lg'] as const).map((s) => (
<AvatarGroup key={s} aria-label={`Signers ${s}`} size={s} max={4}>
{people.map((n) => (
<Avatar key={n} name={n} size={s} />
))}
</AvatarGroup>
))}
</div>
);
}API reference
| Prop | Type | Default | Description |
|---|---|---|---|
children* required | ReactNode | None | Avatar elements. |
max | number | None | Maximum avatars before the "+N" counter. |
total | number | None | Total count when it exceeds the children provided. |
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' | Overflow counter and overlap size; match your avatars. |
overflowLabel | (hidden: number) => string | "N more" | Accessible text for the counter. |
Accessibility
- Rendered as a <ul>, so screen readers announce the number of people. Name it with aria-label.
- The overflow counter is announced as "3 more" (customisable) rather than "+3".
- Each avatar keeps its own accessible name.
Usage guidelines
Do
- Pair the group with a link to the full list when people need details.
Don’t
- Show more than about five avatars before collapsing.