# Avatar group

> Overlapping avatars that spread apart on hover.

Component · Free · https://lodeui.com/components/avatar-group

## When to use

- Showing who is on a team, document or thread.

## When not to use

- A full member list: use a table.

## Installation

```bash
npx shadcn@latest add https://lodeui.com/r/avatar-group.json
```

npm dependencies: motion

## Usage

```tsx title="example.tsx"
import { AvatarGroup } from "@/components/ui/avatar-group";

export function Viewers() {
  return <AvatarGroup people={[{ name: "Ada Lovelace" }, { name: "Grace Hopper" }, { name: "Alan Turing" }]} max={4} />;
}
```

## API reference

### AvatarGroup

Overlapping avatars with a +N chip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| people | `{ name; src?; hue? }[]` | – | People to show. |
| max | `number` | `4` | Shown before +N. |
| size | `number` | `32` | Diameter in px. |

### Avatar

One avatar: image or initials on a hue generated from the name.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name / src / hue / size | `string / string / number / number` | – | Identity and size. |

## Accessibility

- Initials avatars include the full name for screen readers; images use the name as alt.

## Motion

- Overlap springs open on hover.

## Responsive behavior

- Fixed size; reduce max on phones.

## Performance

- Images load lazily by browser default.

## Notes for AI

- Pass hue to keep a person's color stable.

## Related

- [Profile card](https://lodeui.com/components/profile-card) — A portrait whose details rise into a glass panel on hover.
- [Badge](https://lodeui.com/components/badge) — Tone badges and status dots for states like paid, pending, live and degraded.