Avatar
Last Updated: September 2026Avatars are visual depictions of unique users on a product or platform. They support a variety of visual appearances for flexibility on what data is available.
Source CodeAnatomy
link- 1Initials
- 2Image
- 3Icon fallback
Variants
linkInitials
label renders short initials on a strong indigo surface.
Image
imageUrl shows a photo; label is used as the image alt text.
Icon fallback
With no imageUrl or label, a filled person icon appears.
Usage Guidelines
linkWhen to use
- •To represent a user, clinician, or entity beside a name or row.
- •When you need a compact visual identity with initials or a photo.
- •In lists, headers, and comments where faces aid scanning.
When not to use
- •As a standalone action control — wrap with a button or use IconButton.
- •For status indicators — use Dot Status or Tag instead.
- •When you need overlapping stacks — use AvatarGroup (separate component).
Keep initials to 1–2 characters so they stay legible at small sizes.
Don't pass a full display name into label — it will overflow the circle.
Always pass label with imageUrl so the photo has meaningful alt text.
Don't omit label when using imageUrl — the image alt becomes empty.
Behaviors
linkFallback priority
- •When imageUrl is set, the image renders; Base UI Fallback shows when the image fails or is absent.
- •If label is provided (and no usable image), initials Typography is shown.
- •If neither imageUrl nor label is set, a filled person Icon is shown.
Size mapping
- •size controls the circle (xs→size-5, sm→size-7, md→size-9, lg→size-12).
- •Initials use label-xs / label-s / label-m / heading-s by size.
- •Icon fallback rem sizes: xs 1.5, sm 2, md 2.75, lg 4.
Content Guidelines
linkInitials
- •Prefer two uppercase letters from first + last name (synthetic demos only).
- •Avoid real MRNs, emails, or other identifiers in labels.
Images
- •Use square crops; the image uses object-cover inside the circle.
- •Provide a stable label for alt text even when the photo is decorative in context.
Accessibility
linkText & Labels
- •Pass label whenever possible — it becomes the image alt and the initials text.
- •If the avatar is purely decorative beside a visible name, ensure the name is still announced elsewhere.
ARIA attributes
- •The root is a Base UI Avatar root; add aria-label on the root when the avatar is the only identifier.
- •Do not put interactive roles on Avatar itself — wrap with a button or link when clickable.
Keyboard Support
- •Avatar is not focusable by default.
- •If wrapped in a control, Tab focuses the wrapper; Space/Enter activates it.
WCAG Compliance Standards
FAQs
linkIs there an initials prop?
No — use label for short initials. There is no separate initials API.
What happens if the image fails to load?
Base UI shows the Fallback: label initials if provided, otherwise the person icon.
How do I show a stack of avatars?
Use AvatarGroup with an items array and optional max — it is a sibling component, not part of Avatar props.