# AvatarGroup

> A stack of overlapping avatars with a "+N" overflow, announced as a list.

Category: Data display · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/avatar-group

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.

## Import

```tsx
import { AvatarGroup, Avatar } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
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>
  );
}
```

### Overflow

```tsx
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>
  );
}
```

### Sizes

```tsx
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

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| AvatarGroup | `children` (required) | `ReactNode` | None | Avatar elements. |
| AvatarGroup | `max` | `number` | None | Maximum avatars before the "+N" counter. |
| AvatarGroup | `total` | `number` | None | Total count when it exceeds the children provided. |
| AvatarGroup | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Overflow counter and overlap size; match your avatars. |
| AvatarGroup | `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.

## 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.

## Related

- https://stanceui.com/components/avatar