# Avatar

A circle that stands for a person, team or workspace: their photo, or one or two initials on a hue pair when there is no photo or it fails to load. Soft by default; solid inside a Token or on a photo or gradient.

## Cách dùng

### Khi nào dùng

- Show who a piece of content belongs to: a comment author, an assignee, the members of a team.
- Stand in for a missing or slow photo with one or two initials on a soft hue.

### Khi nào không dùng

- A logo, a product image or a picture in content. Use a native img.
- A person picked as a value, such as a recipient in a field. Use Token with a leading avatar.
- A status such as online or busy. Use Badge next to the name.
- The only place a name appears in a list or comment. Write the name next to the avatar.

## Biến thể

### variant

soft: background-<hue> with text-<hue>, for lists and comment headers. solid: the <hue> solid with text-on-<hue>, inside a Token or on a photo or gradient where the soft fill would not stand out.

Giá trị: `soft`, `solid`. Mặc định: `soft`.

### color

The hue pair behind the initials. Never the accent. To keep one person's color across a page, pick the hue from something stable, such as their user id.

Giá trị: `gray`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`. Mặc định: `gray`.

### size

sm 24px for dense lists and table rows, md 32px for comment headers and member lists, lg 40px for profile headers.

Giá trị: `sm`, `md`, `lg`. Mặc định: `md`.

## Ví dụ

### Default

```tsx
<Avatar alt="Ada Lovelace">AL</Avatar>
```

### With photo

The initials show until the photo loads, and stay if it fails.

```tsx
<Avatar src="/avatars/ada.jpg" alt="Ada Lovelace" color="blue">
  AL
</Avatar>
```

### Next to a name

The name is written next to the avatar, so alt is empty and the avatar is hidden from screen readers.

```tsx
<div className="flex items-center gap-sm">
  <Avatar alt="" color="teal" size="sm">
    GH
  </Avatar>
  <span className="text-sm text-text-primary">Grace Hopper</span>
</div>
```

### Without a name

An icon on the soft variant, for a guest or a deleted account.

```tsx
<Avatar alt="Guest">
  <IconUser size={16} />
</Avatar>
```

## Nên và không nên

### Nên

- Pass the person's name as alt, or alt="" when the name is written next to the avatar.
- Always pass initials as children, even with src, so a slow or broken photo still shows something.
- Use solid inside a Token or on a photo or gradient; use soft everywhere else.
- Keep one hue per person across the page.

### Không nên

- Don't put an icon on a solid avatar; there is no icon token for a hue solid.
- Don't use the accent or a status color as the fill.
- Don't let the avatar replace a visible name in lists, comments or assignee fields.
- Don't use it for logos or product images; use a native img.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `variant` | `enum` | `soft`, `solid` | `soft` | soft: background-<hue> with text-<hue>, for lists and comment headers. solid: the <hue> solid with text-on-<hue>, inside a Token or on a photo or gradient where the soft fill would not stand out. |
| `color` | `enum` | `gray`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink` | `gray` | The hue pair behind the initials. Never the accent. To keep one person's color across a page, pick the hue from something stable, such as their user id. |
| `size` | `enum` | `sm`, `md`, `lg` | `md` | sm 24px for dense lists and table rows, md 32px for comment headers and member lists, lg 40px for profile headers. |
| `src` | `string` |  |  | Photo URL. The initials show until it loads, and stay if it fails. |
| `alt` (bắt buộc) | `string` |  |  | Name of the person, team or workspace: Ada Lovelace. Pass an empty string when the name is written next to the avatar. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `fallback` | có | One or two initials, such as AL. On the soft variant, an icon for someone without a name. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | The circle: radius-full, the hue fill, and the name of the avatar. 24, 32 or 40px. |
| `image` | The photo, cropped to fill the circle. Rendered only once it has loaded, then it fades in with duration-medium (no fade under reduced motion). |
| `fallback` | The children: one or two initials in medium weight, shown until the photo loads and when it fails or is missing. |
| `icon` | Optional Tabler icon as the fallback on the soft variant, 12px in sm, 16px in md, 20px in lg. |

## Khả năng truy cập

Role: `img`

- alt names the avatar on the root (role img with aria-label), so the name is the same whether the photo loads or the initials show, and the initials are never read out letter by letter. The type requires alt.
- When the name is written next to the avatar, as in a comment header or a member list, pass alt="": the avatar is hidden from screen readers, so the name is not read twice.
- Avatar is not interactive. To open a profile, put the avatar and the name inside one link, and name the link.
- The hue is decoration. Never let it carry meaning such as a role or a status on its own.
- Solid initials use text-on-<hue>, which meets 4.5:1 on every hue in both modes. There is no icon token for a hue solid, so an icon fallback is for the soft variant only.

## Cài đặt

```bash
npx shadcn add https://werewolf-ui.vercel.app/r/avatar.json
```

Lệnh này thêm luôn `styles/werewolf.css`, bộ token mà mọi component dùng, và các component khác mà nó cần. Import file đó một lần trong CSS gốc, ngay sau `@import "tailwindcss"`, với đường dẫn tính từ file CSS đó (từ `app/globals.css` là `@import "../styles/werewolf.css"`).