Avatar

An image element with a fallback for representing the user.

Features

Automatic fallback
Accessible defaults
Image lifecycle hooks
Group support
Headless

Installation

npm install @ariaui/avatar

Examples

The first block covers a photo plus initials fallback, then an initials-only root without src. The last example stacks overlapping faces in a shared Avatar.Group using local /avatar.png.

With image

Provide src and alt, and pass fallback for loading and error states.

Preview

No preview output yet.

live.tsxReady

Initials

Omit src to show the fallback until you wire a real image URL.

Preview

No preview output yet.

live.tsxReady

Overlapping row

Stack circular roots with negative horizontal spacing on Avatar.Group; add borders to separate faces.

Preview

No preview output yet.

live.tsxReady

Anatomy

tsx

import * as Avatar from "@ariaui/avatar";

export default function Example() {
  return (
    <>
      <Avatar.Root />
    
      <Avatar.Group>
        <Avatar.Root />
        <Avatar.Root />
      </Avatar.Group>
    </>
  );
}

API Reference

Root

The main avatar container. Renders the image when loaded; shows the fallback while loading or on error. Applies role="img" and aria-label="avatar" automatically while the fallback is visible.

Prop	Type	Default
src	string	—
alt	string	""
fallback	React.ReactNode	—
onLoad	React.ReactEventHandler<HTMLImageElement>	—
onError	React.ReactEventHandler<HTMLImageElement>	—

Attribute	Values
role="img"	Present while image is loading or unavailable
aria-label="avatar"	Present while fallback is visible; removed once image loads

Group

A semantic wrapper for a collection of Avatar.Root elements. Applies role="group" so screen readers can identify a set of related avatars.

Attribute	Values
role="group"	Always present on the Group wrapper

Keyboard

Shortcut	Action
`Tab`	Move focus to the next focusable control (for example links or buttons you place near or inside an avatar).
`Shift`+`Tab`	Move focus to the previous focusable control.

Accessibility

There is no dedicated WAI-ARIA APG pattern for avatars. Avatar.Root applies role="img" and aria-label="avatar" while the fallback is visible; once the image loads, those defaults are removed and the internal image follows MDN guidance on image accessibility via alt.

Alt text

Provide a meaningful alt whenever the photo identifies the user. Use alt="" only when the avatar is purely decorative and nearby text already names the person.

Groups

Use Avatar.Group when multiple avatars represent one related set (for example participants). The default role="group" signals that relationship to assistive technology.