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.
No preview output yet.
Initials
Omit src to show the fallback until you wire a real image URL.
No preview output yet.
Overlapping row
Stack circular roots with negative horizontal spacing on Avatar.Group; add borders to separate faces.
No preview output yet.
Anatomy
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 | — |
fallbackDelayMs | number | — |
imgProps | Omit<React.ComponentPropsWithoutRef<"img">, "alt" | "onError" | "onLoad" | "src"> | — |
onLoad | React.ReactEventHandler<HTMLImageElement> | — |
onError | React.ReactEventHandler<HTMLImageElement> | — |
onLoadingStatusChange | (status: "idle" | "loading" | "loaded" | "error") => void | — |
| Attribute | Values |
|---|---|
| role="img" | Present while image is loading or unavailable |
| aria-label="avatar" | Present while fallback is visible; removed once image loads |
Image
Independent image part. It renders a hidden <img> while loading, reports loading status to Root, and becomes visible after load.
| Prop | Type | Default |
|---|---|---|
src | string | — |
alt | string | — |
onLoadingStatusChange | (status: "idle" | "loading" | "loaded" | "error") => void | — |
| Attribute | Values |
|---|---|
| aria-hidden="true" | Present while the image is loading or failed |
Fallback
Independent fallback part. It renders while the current image status is not loaded and can delay its appearance.
| Prop | Type | Default |
|---|---|---|
delayMs | number | — |
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.