Search docs

Avatar

An image that represents a user, with a fallback shown while it loads or when it fails.

There is no WAI-ARIA APG pattern for avatars. Avatar renders a native <img>, so the image is named by its alt text like any other image.

LU
import { component$, useStyles$ } from '@builder.io/qwik';
import { Avatar } from '@leve-ui/avatar';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Avatar.Root class="avatar-default">
      <Avatar.Image
        src="https://i.pravatar.cc/96?img=5"
        alt="Sample user"
        width={48}
        height={48}
        class="avatar-default-image"
      />
      <Avatar.Fallback class="avatar-default-fallback">LU</Avatar.Fallback>
    </Avatar.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/avatar

Anatomy#

import { Avatar } from '@leve-ui/avatar'; // or '@leve-ui/core'

<Avatar.Root>
  <Avatar.Image />
  <Avatar.Fallback />
</Avatar.Root>
PartElementDescription
Avatar.Root<span>Wraps the image and the fallback, and tracks the loading status.
Avatar.Image<img>The image. Hidden until it has loaded.
Avatar.Fallback<span>Shown while the image is loading, when it fails, or when there is no src. Removed once the image has loaded.

Examples#

Fallback#

When the image fails to load, the fallback (here, initials) stays visible.

LU

API Reference#

Root#

PropDefaultType
onStatusChange$–QRL<(status: 'idle' | 'loading' | 'loaded' | 'error') => void>

Called when the loading status of the image changes.

Also accepts all <span> attributes.

Data attributeValue
data-leve-avatarAlways present

The Root has no data-state: the loading status is decided by the Image, which is rendered after the Root (ADR 0010). To style the Root by status, use :has(), for example [data-leve-avatar]:has([data-leve-avatar-image][data-state="loaded"]).

Image#

No props of its own. Accepts all <img> attributes.

Data attributeValue
data-leve-avatar-imageAlways present
data-state"idle" | "loading" | "loaded" | "error"

The image has the hidden attribute until its status is "loaded".

Fallback#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-avatar-fallbackAlways present
data-state"idle" | "loading" | "error"

Accessibility#

  • Always pass alt to Avatar.Image. Describe who the image represents (for example, the user's name). If the user's name is already shown next to the avatar, use alt="" so that screen readers do not read it twice.
  • The fallback is plain text and is read by screen readers while it is shown. If it only repeats a name that is visible nearby, hide it with aria-hidden="true".
  • Avatar has no keyboard interaction. If the avatar is a link or a button, wrap it in an <a> or <button> with an accessible name.