# Avatar

Represents a user or entity as an image, with a blank placeholder while the image is missing or fails to load.

## Use for

- showing a user or organization image
- a profile picture with a fallback

## Practices

- Do: Pass `alt` on `Avatar.Image`.
- Don't: Expect initials passed to `Avatar.Fallback` to show. They stay hidden so a missing picture reads as an absent image.

## API reference

### Avatar.Root

Sizes and shapes the box, and renders polymorphically.

Slot: `cl-avatar`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bordered` | `boolean` | `true` | Draws a 1px inset outline so the avatar keeps an edge on a matching background. |
| `shape` | `'circle' \| 'square'` | `'circle'` | Circle or square. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'fit'` | `'md'` | Box size. `fit` fills the parent. |

### Avatar.Image

Renders the `<img>` once the source loads, and nothing before then.

Slot: `cl-avatar-image`

### Avatar.Fallback

Holds the space while the image is pending or failed. Carries `data-pending` while resolving.

Slot: `cl-avatar-fallback`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delayMs` | `number` |  | Waits this long before rendering, to avoid a flash on fast loads. |

### Avatar.Icon

An optional icon over the corner of the avatar.

Slot: `cl-avatar-icon`
