CONTENT DISPLAY

Avatar

Draft

Displays a user's profile image with a graceful initials fallback when no image is available.

Usage

JSBW

Common alternative names

Profile image, User icon, Thumbnail

---

Anatomy

An avatar displays a user representation inside a circular container. The content changes depending on whether an asset (photo) is available.

Asset added

Circle container
(Required)

Photo
(Recommended)

No asset added (fallback)

Background fill
(Required)

AB

Letters
(Recommended)

👤

Vector
(Optional)

☺

Icon
(Optional)

AB

Badge
(Optional)

Usage guidelines coming soon.

Specs

Specs coming soon.

Content

Content guidelines coming soon.

Status & changelog

Status & changelog coming soon.

Code

---

Usage

import { Avatar } from '@arch-ui/components';

// With an image
<Avatar src="/images/jane.jpg" name="Jane Doe" />

// Initials fallback (no src)
<Avatar name="John Smith" />

Sizes

Six sizes are available, from compact UI elements to large profile displays.

<Avatar name="AB" size="xsmall" />   {/* 24px */}
<Avatar name="AB" size="small" />    {/* 36px */}
<Avatar name="AB" size="medium" />   {/* 48px -- default */}
<Avatar name="AB" size="large" />    {/* 64px */}
<Avatar name="AB" size="xlarge" />   {/* 80px */}
<Avatar name="AB" size="xxlarge" />  {/* 112px */}

---

Shapes

<Avatar name="Jane Doe" shape="circle" />  {/* default */}
<Avatar name="Jane Doe" shape="square" />

---

Image error fallback

When the src image fails to load, the component automatically falls back to displaying the user's initials. No extra handling is needed.

<Avatar src="/broken-link.jpg" name="Jane Doe" />
{/* Renders "JD" initials */}

---

Props

Prop	Type	Default	Description
src	string	--	URL of the avatar image. Falls back to initials when absent or on error.
name	string	required	Full name. Drives alt text and initials.
size	'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge'	'medium'	Rendered size.
shape	'circle' | 'square'	'circle'	Shape of the avatar.
className	string	--	Additional CSS class names.

---

Accessibility

• When an image is displayed, the <img> element carries alt={name}.
• When initials are shown instead, the root <span> gets role="img" and aria-label={name} so screen readers announce the person's name.
• The initials text is marked aria-hidden="true" since the label already conveys the information.