Avatar

JLPN

Show codeHide code

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

Add

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

---
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.

Sizes

<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

ALALALAL

AL

Show codeHide code

<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 variants, plus squared:

<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):

CWCW

Show codeHide code

<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:

<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.

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

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).