Avatar

Data displaySince 0.9.0

import { Avatar } from '@absoluteui/components/avatar';
import '@absoluteui/components/avatar/style.css';

Using Angular? See Avatar for Angular.

What it does

A picture of a person or entity with fallbacks: the image, then initials from the name, then an optional icon. Avatar is one image to assistive technology (role="img"), named after the person and, when shown, their presence status (“Ada Lovelace, Away”). Set decorative when the name is printed next to it. The component never fetches anything itself; only its image element loads src.

When to use

• Identifying people in lists, comments, assignments, and headers.
• Showing presence (online, away, busy, offline) next to a person.

When not to use

• Several people on one record: use Avatar Group.
• Content images or logos that are not identities: use an img element.

Examples

Initials, presence, sizes, and shapes

import { Avatar, type AvatarSize } from '@absoluteui/components/avatar';

const row = document.createElement('p');
document.body.append(row);
const people: [string, AvatarSize][] = [['Ada Lovelace', 'xs'], ['Grace Hopper', 'sm'], ['Alan Turing', 'md'], ['Barbara Liskov', 'lg'], ['Edsger Dijkstra', 'xl']];
for (const [name, size] of people) {
  const host = document.createElement('span');
  row.append(host, ' ');
  Avatar.create(host, { name, size, status: size === 'md' ? 'online' : null });
}
const team = document.createElement('span');
row.append(team);
Avatar.create(team, { name: 'Platform team', shape: 'square', status: 'busy' });

Decorative avatar next to a printed name

import { Avatar } from '@absoluteui/components/avatar';

const author = document.createElement('p');
const picture = document.createElement('span');
author.append(picture, ' Grace Hopper commented');
document.body.append(author);
// The name is printed next to the avatar, so the avatar is not announced again.
Avatar.create(picture, { name: 'Grace Hopper', size: 'sm', decorative: true });

Usage

import { Avatar } from '@absoluteui/components/avatar';
import '@absoluteui/components/avatar/style.css';

const host = document.querySelector<HTMLElement>('#me');
if (host) Avatar.create(host, { name: 'Grace Hopper', size: 'sm', status: 'busy' });

More usage

import { Avatar } from '@absoluteui/components/avatar';

const host = document.querySelector<HTMLElement>('#owner');
if (host) {
  const owner = Avatar.create(host, { name: 'Ada Lovelace', src: '/avatars/ada.webp', status: 'online' });
  owner.update({ status: 'away' });
}

Anatomy

<span class="aui-avatar aui-avatar--{size} aui-avatar--{shape} aui-avatar--{image|initials|icon}" role="img" aria-label="name[, status]">
  <span class="aui-avatar__visual" aria-hidden="true">
    <img class="aui-avatar__image" alt="">  |  initials  |  icon
  </span>
  <span class="aui-avatar__status" aria-hidden="true"></span>   (presence dot, optional)
</span>

API reference

Factory

Avatar.create(host: HTMLElement, options: AvatarOptions): Avatar

Global configuration key: avatar (see Configuration).

Options

Option	Type	Default	Description
name	string		Accessible name and source of the initials. Required.
src	string | null		Image URL: http(s), relative, blob:, or a base64 PNG, JPEG, GIF, WebP, or AVIF data URL.
icon	IconRef | null		Icon shown when the name yields no initials.
status	'online' | 'away' | 'busy' | 'offline' | null		Presence dot; its name is part of the accessible name.
decorative	boolean	"false"	Hide from assistive technology when the name is shown next to it.
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	"md"	Avatar size. Globally configurable.
shape	'circle' | 'square'	"circle"	Avatar shape. Globally configurable.
locale	string	"en-US"	Locale of status names and initials casing. Globally configurable. Inherited from common configuration.

Properties

Property	Type	Description
host	HTMLElement	The host element (receives role, label, and classes).
name	string	Current name.
shows	'image' | 'initials' | 'icon'	What is currently shown.
options	Readonly<AvatarOptions>	Current options.

Methods

Method	Description
update(options: Partial<AvatarOptions>): void	Merge and apply options; a new src is loaded again even after a failure.
destroy(): void	Remove rendering, attributes, classes, and subscriptions.

CSS classes

All rules live in the aui.components cascade layer, so application styles override them without specificity battles.

Class	Purpose
aui-avatar	Host.
aui-avatar--xs | --sm | --md | --lg | --xl	Size modifiers.
aui-avatar--circle | --square	Shape modifiers.
aui-avatar--image | --initials | --icon	What is shown.
aui-avatar--status-online | -away | -busy | -offline	Presence modifiers.
aui-avatar__visual	Image, initials, or icon (aria-hidden).
aui-avatar__image	The img element.
aui-avatar__status	Presence dot (aria-hidden).

Design tokens

Tokens this stylesheet reads (verified in CI). Override them in a theme or with the Theme Designer.

--aui-border-width | --aui-color-error-fg | --aui-color-success-fg | --aui-color-surface | --aui-color-surface-sunken | --aui-color-text | --aui-color-text-muted | --aui-color-warning-fg | --aui-font-family-sans | --aui-font-weight-semibold | --aui-radius-md | --aui-radius-pill

TypeScript definitions

type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
type AvatarShape = 'circle' | 'square';
type AvatarStatus = 'online' | 'away' | 'busy' | 'offline';
interface AvatarConfig { size: AvatarSize; shape: AvatarShape }
interface AvatarOptions extends Partial<AvatarConfig> {
  name: string;
  src?: string | null;
  icon?: IconRef | null;
  status?: AvatarStatus | null;
  decorative?: boolean;
  locale?: string;
}
function avatarInitials(name: string, locale?: string): string;
function isSafeImageSrc(value: unknown): value is string;

Accessibility

Pattern: Image with a text alternative: role=img on the host, aria-label with the name and presence status.

Keyboard

Key	Context	Action
None	Any	Not focusable; read in document order by assistive technology.

Roles

Element	Role
host	img (absent when decorative)
visual and status dot	none (aria-hidden=true)
img	presentation (alt is empty; the host carries the name)

ARIA attributes

Attribute	Element	Value
aria-label	host	the name, or ‘name, status’ when a status is shown
aria-hidden	host when decorative; visual and status dot always	true

Focus

Never receives or moves focus.

WCAG 2.2 success criteria addressed

Criterion	Level	Note
1.1.1 Non-text Content	A
1.4.1 Use of Color	A
1.4.3 Contrast (Minimum)	AA
1.4.11 Non-text Contrast	AA

Automated test results: Accessibility and compliance.

Notes and known caveats

• Presence is part of the accessible name and has a distinct shape per status, not only a color.
• Set decorative when the person’s name is printed next to the avatar, so it is not read twice.
• Manual screen-reader verification (NVDA, JAWS, VoiceOver) is pending.

Behavior

States

Shows image, initials, or icon; five sizes; circle or square; presence online, away, busy, offline; decorative.

State transitions

From	Trigger	To
image	the image fails to load	initials (or icon); the same URL is not retried
any	update({ src }) with a new URL	image
any	update({ status })	new dot and accessible name
any	destroy()	host restored to empty

Accessibility notes

• Presence is in the accessible name and each status has its own dot shape (busy has a bar, offline is hollow), so it does not depend on color.
• Set decorative when the name is printed beside the avatar, so screen readers do not read it twice.
• The e2e axe run covers three themes; manual screen-reader verification is pending.

Responsive behavior

Fixed size per size step; initials and the dot scale with it.

Right-to-left

The status dot sits at the bottom inline-end corner, mirrored in RTL.

Theming

Initials pair --aui-avatar-fg with --aui-avatar-bg (contrast gate). Forced-colors mode draws a CanvasText boundary and dot.

Global configuration

configureAbsoluteUI({ components: { avatar: { size: 'sm', shape: 'square' } } });

Component configuration

Instance options override global and theme configuration; configuration changes re-render existing avatars.

Icons

icon: any registered icon, shown only when the name has no letters or digits.

Security

src is validated with isSafeImageSrc: http(s), relative, blob:, or base64 data URLs of raster images. javascript:, SVG data URLs, and other schemes are rejected with AVATAR_OPTIONS. The image loads lazily with referrerpolicy="no-referrer". The name is rendered with textContent.

Data handling

Only the image element loads src, without a referrer. No persistence, other network access, or telemetry.

Performance

Constant work per render. Images load lazily and decode asynchronously.

Supported data scale

One avatar per row in lists of thousands of rows (with virtualization where the list itself needs it).

Edge cases

• Initials take the first letter or digit of the first and last word (“Jean-Luc Picard” gives JP); a single word gives one initial.
• A name without letters or digits shows the icon, or else its first character.
• A failed image is not retried until src changes.
• Safe in renderers that discard nodes without calling destroy(), such as Data Table cells: the configuration subscription holds the instance weakly, so a discarded avatar is released.

Errors

Code	Category	Cause
AVATAR_OPTIONS	configuration	Missing or blank name, unsafe src, unknown status, or non-boolean decorative.
ICON_UNKNOWN	configuration	Unknown icon.
CFG_INVALID_VALUE / CFG_UNKNOWN_OPTION	configuration	Invalid size, shape, or locale configuration.

Invalid options throw before the host is modified; an invalid update() leaves the previous state intact.

Known limitations

• Initials follow word order; names written family-name-first show those initials in that order.
• Manual screen-reader verification is pending.

Unsupported scenarios

• Uploading or cropping images.
• Clickable avatars: wrap the avatar in a link or button that carries the name.