Avatar

An image element with a fallback for representing the user.

This coponent uses the useVisibleTask$() hook that eagerly executes code on the client by default when the component becomes visible. You can use strategy prop to determine when the VisibleTask should first execute.

import { component$, useStyles$ } from '@builder.io/qwik';
import { Avatar } from 'qwik-primitives';
import styles from './styles.css?inline';

export const AvatarDemo = component$(() => {
  useStyles$(styles);

  return (
    <div class="wrapper">
      <Avatar.Root class="avatar-root">
        <Avatar.Image
          class="avatar-image"
          src="https://images.unsplash.com/photo-1492633423870-43d1cd2775eb?&w=128&h=128&dpr=2&q=80"
          alt="Colm Tuite"
        />
        <Avatar.Fallback class="avatar-fallback" delayMs={600}>
          CT
        </Avatar.Fallback>
      </Avatar.Root>
      <Avatar.Root class="avatar-root">
        <Avatar.Image
          class="avatar-image"
          src="https://images.unsplash.com/photo-1511485977113-f34c92461ad9?ixlib=rb-1.2.1&w=128&h=128&dpr=2&q=80"
          alt="Pedro Duarte"
        />
        <Avatar.Fallback class="avatar-fallback" delayMs={600}>
          JD
        </Avatar.Fallback>
      </Avatar.Root>
      <Avatar.Root class="avatar-root">
        <Avatar.Fallback class="avatar-fallback">PD</Avatar.Fallback>
      </Avatar.Root>
    </div>
  );
});

Features

  • Automatic and manual control over when the image renders.
  • Optionally delay fallback rendering to avoid content flashing.

Import

import { Avatar } from 'qwik-primitives';

Anatomy

Import all parts and piece them together.

import { component$ } from '@builder.io/qwik';
import { Avatar } from 'qwik-primitives';

export const AvatarDemo = component$(() => {
  return (
    <Avatar.Root>
      <Avatar.Image />
      <Avatar.Fallback />
    </Avatar.Root>
  );
});

API Reference

Root

Contains all the parts of an avatar. This component is based on the span element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
strategy
Description

The strategy to use to determine when the image should load.

  • "intersection-observer" means that image will load when the element is visible in the viewport.
  • "document-ready" means that image will load when the document is ready.
  • "document-idle" means that image will load when the document is idle.
Type
enum
Default
"intersection-observer"
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"avatar"
[data-part]
Values
"root"

Image

The image to render. By default it will only render when it has loaded. You can use the onLoadingStatusChange$ handler if you need more control. This component is based on the img element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
onLoadingStatusChange$
Description

A callback providing information about the loading status of the image. This is useful in case you want to control more precisely what to render as the image is loading.

Type
QRL
Default
No default value
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"avatar"
[data-part]
Values
"image"

Fallback

An element that renders when the image hasn't loaded. This means whilst it's loading, or if there was an error. If you notice a flash during loading, you can provide a delayMs prop to delay its rendering so it only renders for those with slower connections. For more control, use the onLoadingStatusChange$ handler on Avatar.Image. This component is based on the span element.

Props

as
Description

Change the default rendered element for the one passed as, merging their props and behavior.

Read our Composition guide for more details.

Type
FunctionComponent
Default
No default value
delayMs
Description

Useful for delaying rendering so it only appears for those with slower connections.

Type
number
Default
No default value
style
Description

The inline style for the element.

Type
CSSProperties
Default
No default value

Data attributes

[data-scope]
Values
"avatar"
[data-part]
Values
"fallback"

Examples

Avoid flash during loading

By default Avatar.Fallback will render when the image hasn't loaded. This means whilst it's loading, or if there was an error.

If you notice a flash during loading, use the delayMs prop to delay its rendering, so it only renders for those with slower internet connections.

import { component$ } from '@builder.io/qwik';
import { Avatar } from 'qwik-primitives';

export const AvatarDemo = component$(() => {
  return (
    <Avatar.Root>
      <Avatar.Image
        src="https://images.unsplash.com/photo-1492633423870-43d1cd2775eb?&w=128&h=128&dpr=2&q=80"
        alt="Colm Tuite"
      />
      <Avatar.Fallback delayMs={600}>CT</Avatar.Fallback>
    </Avatar.Root>
  );
});