# Avatar

A user image with an initials fallback, a delayed fallback, a status badge and groups.

```ehtml Example
import { Avatar, AvatarBadge, AvatarGroup, AvatarGroupCount } from "@elements/ui/avatar";

<Avatar src={user.photo} alt={user.name} />
<Avatar src={user.photo} alt="Ada Lovelace" delayMs={600}>
  <AvatarBadge label="Online" />
</Avatar>
<AvatarGroup label="Project members">
  <Avatar src={a.photo} alt={a.name} />
  <Avatar src={b.photo} alt={b.name} />
  <AvatarGroupCount count={3} />
</AvatarGroup>
```

## Parts

| Part | What it is |
|---|---|
| `.avatar-image` | The `<img>`, always in the DOM, hidden until it loads. |
| `.avatar-fallback` | Initials or an icon beneath the image. |
| `AvatarBadge` | .avatar-badge, a status dot at the bottom inline end. |
| `AvatarGroup` | .avatar-group, overlapping avatars. |
| `AvatarGroupCount` | .avatar-group-count, the +N chip. |

## Attributes

### Avatar

| Attribute | Type | Default | Description |
|---|---|---|---|
| `src` | `string` | `""` | Image URL. Empty shows the fallback. |
| `alt` | `string` | `""` | The person's name: names the avatar and gives the initials. |
| `fallback` | `string` | `""` | Fallback text. Default: initials from alt. |
| `delayMs` | `number` | `0` | Wait this long after mount before showing the fallback, so a fast image never flashes it. It runs once; a later src shows the fallback at once. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | The theme's control heights. |
| `shape` | `"circle" \| "square"` | `"circle"` | square uses the control radius. |
| `lazy` | `boolean` | `false` | loading="lazy" on the image. |
| `onLoadingStatusChange` | `(status: "idle" \| "loading" \| "loaded" \| "error") => void` | `() => {}` | Called when the image status changes. |
| `class` | `string` | `""` | Extra classes on the root. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Other attributes for the root. |
| `imageAttrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Attributes for the `<img>`: srcset, sizes, crossorigin, referrerpolicy, fetchpriority. |

### AvatarBadge

| Attribute | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | `""` | Names the status, such as "Online". Empty is decorative. |
| `tone` | `"success" \| "accent" \| "warning" \| "danger" \| "muted"` | `"success"` | Dot color. |

### AvatarGroup

| Attribute | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | `""` | Names the group. |

### AvatarGroupCount

| Attribute | Type | Default | Description |
|---|---|---|---|
| `count` | `number` | `0` | Renders +count. |
| `size` | `"auto" \| "sm" \| "md" \| "lg"` | `"auto"` | auto matches the group's avatars; a size overrides it. |
| `label` | `string` | `""` | Accessible name. Default: "N more". |

## Slots

| Slot | Part | Content |
|---|---|---|
| `fallback` | `Avatar` | Content in place of the initials, such as an `<Icon>`. |
| `default` | `Avatar` | An AvatarBadge. |
| `default` | `AvatarBadge` | An icon inside the dot. |
| `default` | `AvatarGroup` | Avatars and an AvatarGroupCount. |
| `icon` | `AvatarGroupCount` | Replaces +count, for an icon. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-status` | `"idle" \| "loading" \| "loaded" \| "error"` | root |
| `data-delayed` | present while the fallback waits | root |
| `data-starting-style` | for one frame as the image appears | image |
| `data-ending-style` | while the image goes; visible until its transition ends | image |
| `data-size` | `"sm" \| "md" \| "lg"` | root |
| `data-shape` | `"circle" \| "square"` | root |
| `data-tone` | the tone | AvatarBadge |

## Accessibility

- The image's alt names the avatar. While it loads or after it fails, the fallback is role="img" with the same name.
- Without alt the avatar is decorative.
- A badge with a label is announced ("Online"); without one it is hidden.
- AvatarGroup is a labelled group, and the count reads as "3 more".
- Loading, failing and the fallback delay change what is visible inside a fixed square, never the layout.

## See also

- [Badge](badge): A small label for a status, a count or a category, built on the pill.
- [Card](card): A surface with a header, body and footer, built on the base card styles.
- [Alert](alert): A callout that draws attention to a message, with an icon, a title and an action.
- [Icon](icon): An inline stroke icon from the set the templates draw their own controls with, sized in pixels and colored by the text around it.
- [Kbd](kbd): A keyboard key or shortcut, as text.
- [Separator](separator): A horizontal or vertical rule between content, semantic or decorative.