# Avatar

A person or workspace as an illustrated photo, initials or an icon, with presence, a story ring and overlapping groups.

Tier: Free

## Installation

```bash
npx shadcn add @fetaui/avatar
```

## Usage

```tsx
import { Avatar, AvatarGroup } from '@/components/fetaui/avatar'

export function Example() {
  return (
    <>
      <Avatar src="/mira.jpg" initials="MV" alt="Mira Vale" badge="online" />
      <AvatarGroup label="Team" items={team} onCountClick={openList} />
    </>
  )
}
```

## API

| Prop | Type | Default |
|---|---|---|
| src | string |  |
| person | mira, kai, lena, omid |  |
| initials | string |  |
| icon | ReactNode | person glyph |
| loading | boolean | false |
| alt | string | '' |
| size | xs, sm, md, lg, xl | md |
| shape | circle, rounded | circle |
| ring | boolean, live | false |
| badge | online, away, busy, offline, verified, edit |  |
| badgeLabel | string | the type |
| animated | boolean | true |
| AvatarGroup items | Avatar props[] | required |
| AvatarGroup label | string | required |
| AvatarGroup size | sm, md, lg | md |
| AvatarGroup overflow | none, count, add | count |
| AvatarGroup max | number | 4 |
| AvatarGroup onCountClick | () => void |  |
| AvatarGroup onAdd | () => void |  |

## When to use

- A real photo when you have one, an illustrated person for new accounts, initials for teams.
- Keep one shape per list. Rounded is for teams and workspaces.
- Show presence only where it changes what people do next.

## When not to use

- As a button on its own: wrap it in a real button with a label.
- For a logo on a marketing page: use an image.

## Accessibility

- Give photos alt text with the name. Use empty alt when a visible name sits next to the avatar.
- Presence is announced in text, never by colour alone.
- The group is a labelled group, and +N says how many more.

## Motion

- Images fade in over 200 ms on the Loading fill, and fall back to the person, then initials, on error.
- Changing the person crossfades and settles on a 420 ms spring.
- A new badge pops 0 to 1.15 to 1 in 240 ms.
- A live ring turns once every 1200 ms and pauses off screen.
- Group hover spreads the faces in 150 ms.
- With reduced motion, the person crossfades in 120 ms, the ring holds still and the group stays put.