# AvatarStack

A few people as Avatars that overlap in a row, the first on top, then a +N circle for the rest. Use it for who is typing, who has seen a message or who is in a call; for one circle that stands for a whole group, use GroupAvatar.

**Dependencies:** npm: 0 direct, 3 total; registry: 3 direct, 3 total.

## Usage

### When to use

- Show a few people at once: who is typing, who has seen a message, who is in a call.
- Hint at the members of a project in a small space, with +N for the rest.

### When not to use

- One circle for a whole group or team. Use GroupAvatar.
- A list of people to read and pick from. Use a list with Avatar and names.
- One person. Use Avatar.

## Variants

### size

The size of the avatars: the overlap and the +N circle follow it. Default: the first avatar's size, else md.

Values: `sm`, `md`, `lg`. Default: `undefined`.

## Examples

### Three people

```tsx
<AvatarStack label="Linh, An and Minh">
  <Avatar alt="" color="blue">LT</Avatar>
  <Avatar alt="" color="green">AP</Avatar>
  <Avatar alt="" color="purple">M</Avatar>
</AvatarStack>
```

### More than max

People past max fold into a +N circle.

```tsx
<AvatarStack max={3} label="Linh, An, Minh and 2 others">
  <Avatar alt="" color="blue">LT</Avatar>
  <Avatar alt="" color="green">AP</Avatar>
  <Avatar alt="" color="purple">M</Avatar>
  <Avatar alt="" color="orange">B</Avatar>
  <Avatar alt="" color="teal">H</Avatar>
</AvatarStack>
```

### Seen by

Small avatars under a message say who has read it.

```tsx
<div className="flex items-center gap-xs text-xs text-text-secondary">
  <AvatarStack size="sm">
    <Avatar alt="" size="sm" color="blue">LT</Avatar>
    <Avatar alt="" size="sm" color="green">AP</Avatar>
  </AvatarStack>
  Seen by Linh and An
</div>
```

## Do and don't

### Do

- Keep max at 3 or 4; the +N circle counts the rest.
- Give every avatar the same size, and pass that size.
- Name the people in text next to the stack, or with label.

### Don't

- Do not use a stack for one group; use GroupAvatar.
- Do not mix sizes in one stack.
- Do not make each avatar a link; the overlap leaves them too small to press.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `children` (required) | `node` |  |  | Avatars of one size, with alt="". |
| `max` | `number` |  | `3` | How many avatars show before the rest fold into +N. |
| `size` | `enum` | `sm`, `md`, `lg` |  | The size of the avatars: the overlap and the +N circle follow it. Default: the first avatar's size, else md. |
| `label` | `string` |  |  | Names the stack for screen readers, such as Linh, An and 2 others. Without it the stack is hidden from them. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | The row, laid out last to first so the first avatar is painted on top without a z-index. |
| `item` | One Avatar, overlapping the next by a quarter of its width, with a 2px ring in the color behind it. |
| `more` | The gray +N circle for the people past max, the size of the avatars. |

## Accessibility

Role: `img`

- With label (EN `Linh, An and 2 others`) the stack is one image named by it; without label it is hidden from screen readers, for when the names are written next to it.
- Pass alt="" to every Avatar inside: the stack, or the text beside it, names them.
- The ring that cuts each avatar out is the color behind the stack (--ring-offset-color, the page by default), so it never adds a color of its own.
- Not interactive. To open the list of people, put the stack in a button and name the button.

## Install

```bash
npx werewolf-ui add avatar-stack
```

Run `npx werewolf-ui init` once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See [Installation](https://www.werewolf-ui.dev/docs/installation.md) for requirements and the alternative registry setup.