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 on Avatar.Root 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>
  );
});

.wrapper {
  display: flex;
  column-gap: 0.75rem;
}

.avatar-root {
  height: 2.5rem;
  width: 2.5rem;
  display: inline-flex;
  justify-content: center;
  align-items: center;
  vertical-align: middle;
  overflow: hidden;
  user-select: none;
  border-radius: 9999px;
  background-color: #f5eeff;
}

.avatar-image {
  width: 100%;
  height: 100%;
  object-fit: cover;
  border-radius: inherit;
}

.avatar-fallback {
  height: 100%;
  width: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background-color: #f5eeff;
  color: #43009db8;
  font-size: 1.125rem;
  line-height: 2.5rem;
  letter-spacing: -0.0025em;
  font-weight: 500;
  border-radius: inherit;
  overflow: hidden;
}

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';

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

Root

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

Prop	Default	Type
`as`	No default value	`FunctionComponent` Change the default rendered element for the one passed as, merging their props and behavior. Read our Composition guide for more details.
`strategy`	`"intersection-observer"`	`"intersection-observer" \| "document-ready" \| "document-idle"` 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.
`style`	No default value	`CSSProperties` The inline style for the element.

Data attribute	Values
`[data-scope]`	`"avatar"`
`[data-part]`	`"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.

Prop	Default	Type
`as`	No default value	`FunctionComponent` Change the default rendered element for the one passed as, merging their props and behavior. Read our Composition guide for more details.
`onLoadingStatusChange$`	No default value	`QRL<(status: "idle" \| "loading" \| "loaded" \| "error") => void>` 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.
`style`	No default value	`CSSProperties` The inline style for the element.

Data attribute	Values
`[data-scope]`	`"avatar"`
`[data-part]`	`"image"`

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.

Prop	Default	Type
`as`	No default value	`FunctionComponent` Change the default rendered element for the one passed as, merging their props and behavior. Read our Composition guide for more details.
`delayMs`	No default value	`number` Useful for delaying rendering so it only appears for those with slower connections.
`style`	No default value	`CSSProperties` The inline style for the element.

Data attribute	Values
`[data-scope]`	`"avatar"`
`[data-part]`	`"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';

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>
  );
});