◇

Avatar

3 parts

An image element representing a user, with a graceful text/icon fallback for when the image is loading or fails to load. Use it for profile pictures in avatars, comment threads, member lists, or anywhere a user identity is shown and you need a reliable placeholder. The root tracks the image's loading status and provides it via context so AvatarImage and AvatarFallback can coordinate which one is rendered. It exposes the current status on the data-status attribute for styling.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  AvatarRoot,
  AvatarImage,
  AvatarFallback,
} from '@robonen/primitives/display/avatar';

<AvatarRoot>
  <AvatarImage />
  <AvatarFallback />
</AvatarRoot>

API Reference

AvatarRoot

Root

An image element representing a user, with a graceful text/icon fallback for when the image is loading or fails to load. Use it for profile pictures in avatars, comment threads, member lists, or anywhere a user identity is shown and you need a reliable placeholder. The root tracks the image's loading status and provides it via context so `AvatarImage` and `AvatarFallback` can coordinate which one is rendered. It exposes the current status on the `data-status` attribute for styling.

No props or events — renders its element and forwards attributes.

AvatarImage

Image

The image to display. It loads the `src` out of band and only renders once the image has successfully loaded, reporting its loading status to the root so the fallback can take over while loading or on error. A browser-cached image is detected synchronously, so an already-loaded avatar shows instantly without a fallback flash.

Prop	Type	Default	Description
`src`?	`string`	—	Image source URL — loaded out of band before the image is shown.
`alt`?	`string`	—	Alternative text describing the image.
`referrerPolicy`?	`ImgHTMLAttributes['referrerpolicy']`	—	Referrer policy applied to both the out-of-band preload and the rendered image, so the displayed `<img>` reuses the preload cache entry.
`crossOrigin`?	`ImgHTMLAttributes['crossorigin']`	—	CORS setting applied to both the out-of-band preload and the rendered image (required for canvas tainting / credentialed CDNs and cache reuse).
`onLoadingStatusChange`?	`(status: AvatarImageLoadingStatus) => void`	—	Called whenever the image's loading status changes (`idle`/`loading`/`loaded`/`error`).

AvatarFallback

Fallback

Content shown while the image is loading or when it fails to load — typically the user's initials or a generic icon. It renders only when the image is not yet `loaded`, and can be delayed to avoid a flash of fallback on fast connections.

Prop	Type	Default	Description
`delayMs`?	`number`	—	Delay in ms before rendering the fallback (avoids flicker on fast networks).