# GroupAvatar

One circle the size of an Avatar for a group, split into tiles instead of stacked: one member fills it, two split it in halves, three take a half and two quarters, four or more take four quarters with +N for the rest. Use it for a group chat or a team.

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

## Usage

### When to use

- Stand for a group chat or a team with one circle, such as in ConversationList.
- Show a group's members inside the space of one Avatar.

### When not to use

- Show several people side by side. Use AvatarStack.
- One person. Use Avatar.
- A workspace or brand with its own logo. Use Avatar with src.

## Variants

### size

sm 24px, md 32px, lg 40px, as Avatar.

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

## Examples

### Group sizes

Two, three, four and more members.

```tsx
<div className="flex items-center gap-md">
  <GroupAvatar alt="Linh and An" members={pairMembers} />
  <GroupAvatar alt="Launch crew" members={trioMembers} />
  <GroupAvatar alt="Design team" members={designTeam} />
  <GroupAvatar alt="Company" members={companyMembers} />
</div>
```

### Beside a name

With the group's name written next to it, alt is empty.

```tsx
<div className="flex items-center gap-sm">
  <GroupAvatar alt="" size="lg" members={designTeam} />
  <span className="text-sm font-medium text-text-primary">Design team</span>
</div>
```

## Do and don't

### Do

- Use lg next to two lines of text, as in ConversationList.
- Pass photos when you have them; letters are the fallback.
- Keep the members' order stable, so the circle does not change between visits.

### Don't

- Do not use it for a list of people to tell apart; use AvatarStack.
- Do not use sm for groups of three or more where letters matter; the tiles are too small for them.
- Do not put a status dot on a tile; put it on the circle.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `members` (required) | `{ name: string; src?: string; initials?: string; color?: "gray" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" }[]` |  |  | The members to show, in order. Up to four show; past four, three show and the fourth tile counts the rest. color defaults to blue, green, purple, orange. |
| `alt` (required) | `string` |  |  | The name of the group, such as Design team. Pass an empty string when the name is written next to it. |
| `size` | `enum` | `sm`, `md`, `lg` | `md` | sm 24px, md 32px, lg 40px, as Avatar. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | The circle: 24, 32 or 40px, cut round, holding a grid of tiles with a 2px gap. |
| `tile` | One member: their photo, or the first letter of their initials or name on a soft hue pair. In the 24px circle a split tile shows its color alone. |
| `more` | The gray tile with +N (9+ above 9) when the group has more than four members. |

## Accessibility

Role: `img`

- alt names the group (EN `Design team`) on the circle, one image for screen readers. Pass alt="" when the name is written next to it.
- The tiles, their letters and photos are hidden from screen readers; the group's name is what counts.
- The hues are decoration, as on Avatar.

## Install

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

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.