# Avatar

## Overview

Displays a user's identity visually — either as a profile photo or as an initials-based fallback. Used in headers, sidebars, comment threads, and table rows to represent people.

---

## When to Use

- User profile representation in headers and sidebars
- Author attribution in activity feeds and comment lists
- List items that represent people or organizations

---

## Anatomy

```
<Avatar>
  <AvatarImage />    ← Actual photo
  <AvatarFallback /> ← Shown when image fails or hasn't loaded
</Avatar>
```

---

## Props

### Avatar

| Prop        | Type     | Default | Required | Description                                                  |
| ----------- | -------- | ------- | -------- | ------------------------------------------------------------ |
| `className` | `string` | —       | No       | Size and shape overrides (default: `h-10 w-10 rounded-full`) |

### AvatarImage

| Prop  | Type     | Required | Description                 |
| ----- | -------- | -------- | --------------------------- |
| `src` | `string` | No       | Image URL                   |
| `alt` | `string` | No       | Accessible alternative text |

### AvatarFallback

| Prop        | Type        | Description                            |
| ----------- | ----------- | -------------------------------------- |
| `className` | `string`    | Style the fallback background and text |
| `children`  | `ReactNode` | Initials string or fallback icon       |
| `delayMs`   | `number`    | Delay before fallback appears (ms)     |

---

## Examples

### With Image + Fallback Initials

```tsx
import { Avatar, AvatarImage, AvatarFallback } from 'xertica-ui/ui';

<Avatar>
  <AvatarImage src="https://github.com/johndoe.png" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>;
```

### Small (in table rows)

```tsx
<Avatar className="h-8 w-8">
  <AvatarImage src={user.avatar} alt={user.name} />
  <AvatarFallback className="text-xs">{user.name.charAt(0).toUpperCase()}</AvatarFallback>
</Avatar>
```

### With Icon Fallback

```tsx
import { User } from 'lucide-react';

<Avatar>
  <AvatarImage src={user.avatar} />
  <AvatarFallback className="bg-primary/10 text-primary">
    <User className="w-4 h-4" />
  </AvatarFallback>
</Avatar>;
```

---

## AI Rules

- Always include `<AvatarFallback>` — never render `<AvatarImage>` alone. If the image fails to load, the component will be blank without a fallback.
- The fallback should be initials (`user.name.charAt(0)`) or a `lucide-react` user icon — never an external image.
- Size the Avatar using `className="h-8 w-8"` (small) or `className="h-10 w-10"` (default). Do not use Tailwind `w-` and `h-` classes that don't correspond to standard rem multiples.

---

## Related Components

- [`Header`](./header.md) — Avatar is used in the user profile dropdown
- [`Sidebar`](./sidebar.md) — Avatar in the sidebar footer