# Avatar

> A face, or initials until there is one: the photo rises out of a blur once it has loaded, and a stack of avatars fans open when you point at it.

Avatars usually flash an empty circle or a broken image while the photo loads. Here the initials show at once and the photo comes up out of a blur over them once decoded. A status dot sits on the edge, cut out by a ring of the background. AvatarGroup overlaps faces, fans them open on hover so each shows whole, and rolls its "+N".

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/avatar.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `ui-interaction-motion`
- Docs and live preview: https://hairlineui.com/ui/avatar
- Registry item (source): https://hairlineui.com/r/avatar.json

## Usage

```tsx
import { Avatar, AvatarGroup } from "@/components/ui/avatar";

<Avatar name="Ada Okafor" src="/ada.jpg" status="online" />
<AvatarGroup people={members} max={4} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | – | Initials and the accessible name. |
| `src` | `string` | – | Photo URL. |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | 20, 28, 36 or 48px. |
| `status` | `"online" \| "away" \| "busy" \| "offline"` | – | Presence dot. |
| `shape` | `"circle" \| "square"` | `"circle"` | Square for teams. |
| `AvatarGroup` | `{ people, max, size }` | – | Overlapping stack with +N. |

## States

- **loading**: Initials on a muted circle.
- **loaded**: The photo fades in from a 6px blur at 1.08 (360–520ms).
- **group hover**: The overlap opens to a 4px gap; +N rolls when it changes.

## What it handles

An avatar is shown hundreds of times on a page; a flash of grey or a broken image on each one makes the whole app feel slow.

- **No broken images**: Initials first; the photo replaces them only once loaded, cached ones included.
- **Presence**: online, away, busy, offline as a dot with a background ring.
- **Fanning stack**: Hover spreads the group (380ms, 20ms stagger).
- **Four sizes, two shapes**: 20, 28, 36, 48px; circle or rounded square.

## Replaces

avatar with fallback, presence dot, avatar stack

## Where it fits

- **Team and member lists**: A face, name and status in each row.
- **Comments and activity**: Who said what, at 28px.
- **Shared documents**: A stack of collaborators with +N.
- **Workspace switchers**: Square avatars for teams.

## Notes

- role="img" with the name (and status) as its label.
- Reduced motion: the photo fades without blur; the stack doesn't fan.

License: MIT (https://hairlineui.com/license#components)