---
title: "Avatar Group"
description: "A row of overlapping avatars with a count for the members not shown."
---

Use it to say "these people, and some more" in little room: who is in a voice channel, who reacted, who is typing. Show three to five avatars and put the rest in the count.

The count is a prop and not derived from the children, because the total usually comes from the server while only the first few members are loaded.

_Live example of Avatar Group — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add avatar-group
``` Registry dependencies, installed with it: avatar.

Files written — React: components/ui/avatar-group.tsx. Vue: components/ui/avatar-group/AvatarGroup.vue, components/ui/avatar-group/index.ts.

## Usage

React:

```tsx
import { AvatarGroup } from "@/components/ui/avatar-group"
```

Vue:

```ts
import { AvatarGroup } from "@/components/ui/avatar-group"
```

## API reference

**`AvatarGroup`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `overflow` | `number` | `0` | How many members are not shown. Above zero it adds a final "+N" chip. |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Size of the chip. Give the avatars inside the same size. |
| `overflowLabel` | `(count: number) => string` | `(count) => `${count} more`` | What a screen reader says for the chip. |

Each avatar is ringed in the colour of the surface behind it, so the overlap reads as a cut-out. The ring defaults to `--newt-bg-surface`; on another background set `--newt-avatar-group-ring` on the group or any ancestor.

## Accessibility

The group is a `role="group"` and needs a name that says what the people have in common: pass `aria-label`, such as "In voice: 5 members". Initials alone do not identify anybody, so give each avatar an accessible name when who they are matters, or list the names in the label. The chip shows "+2" and is read as "2 more".

`overflowLabel` builds the name of the `+N` chip. [Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Avatar Group reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
