Components

Avatar

Displays a user's profile image inside a circle, gracefully falling back to initials or an icon when the image is missing or fails to load.

Basic usage

Compose an Avatar from an AvatarImage and an AvatarFallback. Radix shows the image once it loads and the fallback otherwise.

AL

Image & fallback

The fallback is automatic — when AvatarImage is absent or its src fails to load, the initials render in its place.

GHATCB

Sizes

The avatar is size-8 by default. Override it with any Tailwind size-* utility — the image and fallback scale to fill the circle.

SMMDLGXL

Avatar group

Overlap avatars with a negative margin and a ring to represent a stack of collaborators, capped with a count.

ALGHKJ+3

Props

Avatar

PropTypeDefaultDescription
classNamestring—Tailwind classes merged onto the root. Override size with size-* and the shape stays a circle.
...restAvatarPrimitive.Root props—All Radix Avatar Root props are forwarded to the wrapper element.

AvatarImage

PropTypeDefaultDescription
srcrequiredstring—URL of the image to display.
altrequiredstring—Alternative text describing the person; required for screen readers.
onLoadingStatusChange(status: 'idle' | 'loading' | 'loaded' | 'error') => void—Fires as the image moves through its loading lifecycle.
classNamestring—Additional Tailwind classes to merge.

AvatarFallback

PropTypeDefaultDescription
delayMsnumber0Wait this many milliseconds before rendering the fallback, avoiding a flash while a fast image loads.
childrenrequiredReact.ReactNode—Content shown when the image is absent or fails — typically initials or an icon.
classNamestring—Additional Tailwind classes to merge.

Accessibility

  • Always pass a descriptive alt on AvatarImage — typically the person's name — so screen readers announce who is shown.
  • Initials in the fallback are decorative; the alt text remains the accessible name even when the image fails to load.
  • Radix only swaps in the fallback after the image errors or while it loads, preventing layout shift and a flash of empty space.
  • Use delayMs on the fallback to avoid a brief initials flicker when the image loads quickly over a fast connection.
  • The avatar is purely presentational — when it acts as a control, wrap it in a <button> or link with its own accessible label.