Avatar ported

A compact identity marker for people and accounts.

A round portrait that falls back to initials and can show an online or offline presence dot.

Live specimen

Loading demo…

Guidance

When to use

Showing one person next to their name, comment, or record.
Presence in a header or list, via the online or offline status dot.
Places where a photo may be missing and initials should stand in.

When not to use

Use Avatar Group for several people with an overflow count.
Use User Menu when the avatar is the trigger for account actions.

Installation

pnpm dlx shadcn-svelte@latest add @arcui/avatar

Usage

<script lang="ts">
  import Avatar from '$lib/components/avatar/avatar.svelte';
</script>

<Avatar name="Maya Chen" src="/people/maya.jpg" size="lg" status="online" />

Variants & Examples

Initials Fallback with Sizes

Scales from sm (28px) to xl (88px) displaying first two letters of name.

<div class="demo-row">
  <Avatar name="Ada Lovelace" size="sm" />
  <Avatar name="Alan Turing" size="lg" />
</div>

Presence Status Dot

Appends online or offline indicator dot with accessible label update.

<Avatar name="Grace Hopper" size="md" status="online" />

Image Source with Fallback

Loads external portrait image with automatic fallback to initials on error.

<Avatar name="Katherine Johnson" src="/photo.jpg" size="xl" />

API Reference

Prop	Type	Default	Description
`name`	`string`	—	Full name. Used for the accessible label and the first two initials.
`src`	`string`	—	Image URL rendered with plain <img>. Falls back to initials if it fails to load.
`size`	`'sm' \| 'md' \| 'lg' \| 'xl'`	'md'	Diameter, from 28px to 88px.
`status`	`'online' \| 'offline'`	—	Adds a presence dot and appends the status to the accessible label.

Accessibility

The root is role="img" with an aria-label of the name plus status, such as "Maya Chen, online".
The image and initials are decorative, so the name is read once by screen readers.
The status dot is aria-hidden; the accessible label carries the presence state.

Motion

Phase 1 still-state: cached photo displays at once and presence dot renders statically. Phase 2 wires the status-dot spring pop and image soft blur fade. Reduced motion drops transitions and swaps states instantly.

Notes for AI

Use for a single person. For a row of people with an overflow count use Avatar Group.
The component is self-contained and needs no Next.js runtime.

Source of truth: registry/components/avatar/avatar.tsx