# Avatar

> A user image, with an initials fallback derived from name.

URL: https://apogee.avaui.dev/docs/avatar
Last updated: 2026-10-15

A user image, with an initials fallback derived from name.

Last updated October 15, 2026

Uses JavaScript

Only for image error recovery: a tiny island removes an image that fails to load so the initials fallback shows instead of a broken-image icon.

**Without JS:** A broken \`src\` shows the browser's default broken-image icon. Everything else is unaffected: loaded images, the initials fallback, and the generic glyph all render server-side — the component's core is zero-JS.

```astro
<Avatar src="https://i.pravatar.cc/80?img=12" name="Jordan Lee" />
<Avatar name="Priya Nair" />
```

## Add

```sh
npx @ava-ui/apogee add avatar
```

Uses `@lucide/astro` (`User`) for the icon shown when neither `src` nor `name` is set. Ships one scoped JS island (progressive enhancement) that swaps a broken image for the initials fallback.

## Usage

```astro
---
import Avatar from '@/components/apogee/Avatar/Avatar.astro'
---
<Avatar src="/users/jordan.jpg" name="Jordan Lee" />
```

## API

`@composable` — exposed to Content Editors in AVA. Any other native `<span>` attribute passes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | — | Image URL. Omit to always show the initials fallback. |
| `alt` | `string` | `name ?? ''` | Alt text for the image. |
| `name` | `string` | — | Used for the initials fallback (first letter of up to the first two words) and as the fallback’s `aria-label`. |
| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` | Diameter 24 / 32 / 40 / 48 / 64px and text size. |
| `status` | `'online' \| 'offline'` | — | A presence dot at the bottom end corner, cut out from the page. Read with the name (“Ana Lima, online”). |
| `border` | `boolean` | `false` | A neutral ring offset from the avatar. |
| `color` | `'primary' \| 'neutral' \| 'critical' \| 'positive' \| 'warning'` | `'neutral'` | Fallback (initials) hue. |
| `variant` | `'solid' \| 'faded'` | `'faded'` | Fallback fill style. |
| `squared` | `boolean` | `false` | Rounded square instead of a circle. |
| `class` | `string` | — | Extra classes, merged last. |

## Sizes

```astro
<Avatar size="xsmall" name="Sam Ito" />
<Avatar size="small" name="Sam Ito" />
<Avatar name="Sam Ito" />
<Avatar size="large" name="Sam Ito" />
<Avatar size="xlarge" name="Sam Ito" />
```

## Status and border

```astro
<Avatar name="Ana Lima" status="online" />
<Avatar name="Ana Lima" status="offline" />
<Avatar name="Ana Lima" border />
<Avatar name="Ana Lima" status="online" border size="large" />
```

## Colours and variants

Every `color` in both `variant`s, plus `squared`:

```astro
<Avatar name="Ana Ruiz" color="primary" />
<Avatar name="Ana Ruiz" color="neutral" />
<Avatar name="Ana Ruiz" color="critical" />
<Avatar name="Ana Ruiz" color="positive" />
<Avatar name="Ana Ruiz" color="warning" />
<Avatar name="Ana Ruiz" color="primary" variant="solid" />
<Avatar name="Ana Ruiz" color="neutral" variant="solid" />
<Avatar name="Ana Ruiz" color="critical" variant="solid" />
<Avatar name="Ana Ruiz" color="positive" variant="solid" />
<Avatar name="Ana Ruiz" color="warning" variant="solid" />
<Avatar name="Ana Ruiz" squared />
```

## States

With an image vs. the initials fallback (no `src`):

```astro
<Avatar src="https://i.pravatar.cc/80?img=5" name="Casey Wren" />
<Avatar name="Casey Wren" />
```

If `src` fails to load, a small JS island removes the `<img>` and shows the initials fallback instead — it also catches images that had already errored before the script ran. Without JS, a broken `src` still shows the browser’s broken-image icon; that’s inherent to an `<img>` with no fallback path.

## Examples

Grouped in a list row:

```astro
<div class="flex items-center gap-2">
  <Avatar src="/users/jordan.jpg" name="Jordan Lee" size="small" />
  <span class="text-sm font-medium">Jordan Lee</span>
</div>
```

For a stack of overlapping avatars, use [`AvatarGroup`](https://apogee.avaui.dev/avatar-group).

## Accessibility

-   With `src`: a real `<img>` with `alt` (falls back to `name`, then empty). Pass `alt` explicitly for a name-less avatar in a meaningful image context.
-   Without `src`, with `name`: the initials fallback gets `role="img"` and `aria-label={name}`.
-   Without `src` and without `name`: a generic Lucide `User` glyph stands in, marked `aria-hidden` as purely decorative — pass `name` (and ideally `src`) whenever the avatar needs to identify someone rather than just fill space.

## Tokens

| Token | Used for |
| --- | --- |
| `--background-neutral` | Initials-fallback background (opaque, so stacked avatars never show through) |
| `--foreground-neutral` | Initials-fallback text |

## Do / Don’t

-   **Do** pass `name` even when you have `src` — it powers the fallback and the accessible label.
-   **Do** use consistent `size` across a single list or group.
-   **Don’t** omit both `src` and `name` if the avatar needs to identify someone — without either, it falls back to a generic decorative icon with no accessible label.
-   **Don’t** put a long name in `alt` when `name` already labels the fallback — keep alt text about the image, not the person’s full title.

## Content

-   `name` is the person’s display name as used elsewhere in the UI — it drives both the initials and the accessible label, so keep it consistent (don’t abbreviate here and spell out elsewhere).

## Related

[

AvatarGroupOverlapping avatars for a compact "who's involved" cluster, with an optional +N overflow chip.

](https://apogee.avaui.dev/docs/avatar-group)[

BadgeA small status label — for counts, tags, and state indicators.

](https://apogee.avaui.dev/docs/badge)[

IconA library-agnostic icon wrapper — forwards a Lucide icon's props, or accepts a raw SVG slot, with built-in accessibility.

](https://apogee.avaui.dev/docs/icon)