Prepared Docs

Avatar from @prepared911/ui-core renders a person or entity as an image, initials, or an icon. The component handles fallback swapping and decorative markup; your job is to decide whether the avatar carries information (name a person) or is decoration (already labeled nearby), and to provide an accessible name for interactive variants.

What the component handles

Image fallback. Missing src or failed loads automatically fall back to initials or an icon.
Initials rendering. getInitials generates initials from a name.
Inverted mode. Applies correct contrast on colored surfaces.

What you must provide

A meaningful alt. When the avatar conveys identity on its own (list of members, unread badge for one person), set alt to the person's full name. When the person's name appears adjacent to the avatar, set alt="" so the same name isn't read twice. See W3C WAI: An alt Decision Tree.
Accessible name for interactive avatars. If the avatar is clickable ("Open profile"), render it inside a button or link with an aria-label that describes the action, not just the person.
Sufficient contrast. Use inverted or an appropriate color mode on dark or colored backgrounds so initials and icons meet 4.5:1 contrast.

Keyboard behavior

Non-interactive avatars are not focusable and require no keyboard support.
Interactive avatars should live inside a Button, IconButton, or link—don't reinvent keyboard handling with tabIndex and onKeyDown.

Semantics and roles

Decorative avatars render as images with alt="" (or as decorative CSS backgrounds).
Informational avatars render as images with a descriptive alt.
Interactive avatars must be wrapped in a button or link for proper semantics.

Known caveats

Duplicated names. An avatar beside a visible name is usually decorative; alt="" keeps the rotor from reading the same name twice.
Initial collisions. Two people with the same initials look identical; supplement with a tooltip or the name adjacent whenever the avatar stands alone.

Avatar / API and Development

Badge / Usage

What the component handles

What you must provide

Keyboard behavior

Semantics and roles

Known caveats

What the component handles

Image fallback. Missing src or failed loads automatically fall back to initials or an icon.
Initials rendering. getInitials generates initials from a name.
Inverted mode. Applies correct contrast on colored surfaces.

What you must provide

A meaningful alt. When the avatar conveys identity on its own (list of members, unread badge for one person), set alt to the person's full name. When the person's name appears adjacent to the avatar, set alt="" so the same name isn't read twice. See W3C WAI: An alt Decision Tree.
Accessible name for interactive avatars. If the avatar is clickable ("Open profile"), render it inside a button or link with an aria-label that describes the action, not just the person.
Sufficient contrast. Use inverted or an appropriate color mode on dark or colored backgrounds so initials and icons meet 4.5:1 contrast.

Keyboard behavior

Non-interactive avatars are not focusable and require no keyboard support.
Interactive avatars should live inside a Button, IconButton, or link—don't reinvent keyboard handling with tabIndex and onKeyDown.

Semantics and roles

Decorative avatars render as images with alt="" (or as decorative CSS backgrounds).
Informational avatars render as images with a descriptive alt.
Interactive avatars must be wrapped in a button or link for proper semantics.

Known caveats

Duplicated names. An avatar beside a visible name is usually decorative; alt="" keeps the rotor from reading the same name twice.
Initial collisions. Two people with the same initials look identical; supplement with a tooltip or the name adjacent whenever the avatar stands alone.

Avatar / API and Development

Badge / Usage

What the component handles

What you must provide

Keyboard behavior

Semantics and roles

Known caveats