Avatar

A person as a picture or initials, wrapping the Base UI Avatar. The fallback shows until the image has actually loaded and stays if it fails, so there's never an empty circle. Always round, independent of the radius setting.

Playground

Turn Image off to see the fallback take over, and Compact to see the initials scale with the circle. The Code tab shows the markup for exactly what you've configured.

Variants

Picture, initials, or an icon for a seat nobody has claimed yet, in both sizes. With the name visible beside it, as in a member list, the image's alt is empty so screen readers don't hear the name twice.

States

Loaded, or not: the fallback shows while the image loads, when it fails, and when there is no picture at all (the second one here). There are no hover or focus states; an avatar isn't interactive on its own.

Styling states

No state attributes beyond data-size; the hooks are the root, the image, and the fallback, so an accent-colored initials disc is one rule:

.ub-avatar-fallback {
  background: var(--ub-accent);
  color: var(--ub-accent-contrast);
}

Props

One component; the image and fallback parts are managed automatically. The essentials:

Agent instructions

Working with a coding agent? Paste this into its context, or point it at llms.txt for the whole library.

Avatar, from @usebones/react.
- One component: src + alt + fallback (initials or an icon); the fallback renders until the image loads and stays on error.
- alt is the person's name; a dev warning fires when src is set without alt. Pass alt="" only when the name is already visible beside the avatar.
- size "default" (36px) | "compact" (28px). Always round regardless of data-radius. Keep initials to two letters.
- Restyle in CSS via .ub-avatar, .ub-avatar-image, .ub-avatar-fallback, [data-size="compact"]. Tokens only.