Avatar

A profile picture, initials, or icon.

Anatomy

<UiAvatarRoot>
  <UiAvatarImage src="" />
  <UiAvatarFallback>LT</UiAvatarFallback>
</UiAvatarRoot>

Examples

Optimized and lazy-loaded images

By default, UiAvatarImage preloads src and renders the img only once it has loaded. That does not compose with <NuxtImg> or loading="lazy".

Pass keepMounted to render the image immediately and let it load in place. Only the image that is actually displayed is requested.

<UiAvatarRoot>
  <UiAvatarFallback>LT</UiAvatarFallback>
  <UiAvatarImage keep-mounted loading="lazy" src="/avatar.jpg" width="32" height="32" alt="" />
</UiAvatarRoot>

Stacking

With keepMounted, the image and the fallback are both present until the image loads. The image is hidden from view until then (visibility, not display: none), so the fallback provides the visible initials.

Stack them in the same box and put UiAvatarImage after UiAvatarFallback. Both are positioned, so whichever comes later paints on top. Hide loading and failed images with data-loading and data-error. The second avatar below uses a missing file so the fallback stays.

With keepMounted, the image is part of the server-rendered HTML and can start loading before hydration. A cached image shows immediately.

API reference

Root

The avatar frame. Renders a <span>. Pass color to tint the fallback wash and initials. The image is unchanged.

Attribute	Description
`data-loading`	Present while the image is loading.
`data-error`	Present when the image failed to load.

Root state imageLoadingStatus is idle, loading, loaded, or error.

Image

The picture. Renders an <img>. Preloads src unless keepMounted is set.

Prop	Type	Default	Description
`src`	`string`	—	Image URL.
`alt`	`string`	`''`	Accessible name. Prefer empty when the fallback already has initials.
`width`	`number \| string`	—	Native width.
`height`	`number \| string`	—	Native height.
`keepMounted`	`boolean`	—	Keep the `img` in the DOM and load in place. Supports `loading="lazy"`.

Emits loadingStatusChange with idle, loading, loaded, or error.

Attribute	Description
`data-loading`	Present while the image is loading.
`data-error`	Present when the image failed to load.
`data-starting-style`	Present when the image begins animating in.
`data-ending-style`	Present when the image is animating out.

Fallback

Shown when the image is missing, loading, or failed. Renders a <span>.

Prop	Type	Default	Description
`delay`	`number`	`0`	Milliseconds to wait before showing the fallback.

Attribute	Description
`data-loading`	Present while the image is loading.