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.
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>
);
});.avatar-default {
display: inline-flex;
align-items: center;
justify-content: center;
width: 48px;
height: 48px;
border-radius: 9999px;
overflow: hidden;
background: light-dark(#daf0ff, #009dfd26);
font-family: inherit;
}
.avatar-default-image {
width: 100%;
height: 100%;
object-fit: cover;
}
/* Initials shown while the image is loading or when it fails */
.avatar-default-fallback {
font-size: 15px;
font-weight: 600;
color: light-dark(#006ce9, #4cb8ff);
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/avatarnpm install @leve-ui/avataryarn add @leve-ui/avatarbun add @leve-ui/avatarpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
import { Avatar } from '@leve-ui/avatar'; // or '@leve-ui/core'
<Avatar.Root>
<Avatar.Image />
<Avatar.Fallback />
</Avatar.Root>
| Part | Element | Description |
|---|---|---|
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.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Avatar } from '@leve-ui/avatar';
import styles from './fallback.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Avatar.Root class="avatar-fallback">
<Avatar.Image src="/not-found.png" alt="Broken image" class="avatar-fallback-image" />
<Avatar.Fallback class="avatar-fallback-fallback">LU</Avatar.Fallback>
</Avatar.Root>
);
});.avatar-fallback {
display: inline-flex;
align-items: center;
justify-content: center;
width: 48px;
height: 48px;
border-radius: 9999px;
overflow: hidden;
background: light-dark(#daf0ff, #009dfd26);
font-family: inherit;
}
.avatar-fallback-image {
width: 100%;
height: 100%;
object-fit: cover;
}
/* Initials shown while the image is loading or when it fails */
.avatar-fallback-fallback {
font-size: 15px;
font-weight: 600;
color: light-dark(#006ce9, #4cb8ff);
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| onStatusChange$ | – | QRL<(status: 'idle' | 'loading' | 'loaded' | 'error') => void> Called when the loading status of the image changes. |
Also accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-avatar | Always 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 attribute | Value |
|---|---|
data-leve-avatar-image | Always 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 attribute | Value |
|---|---|
data-leve-avatar-fallback | Always present |
data-state | "idle" | "loading" | "error" |
Accessibility#
- Always pass
alttoAvatar.Image. Describe who the image represents (for example, the user's name). If the user's name is already shown next to the avatar, usealt=""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.