Avatar

An easily stylable avatar component.

import { Avatar } from '@base-ui/react/avatar';
import styles from './index.module.css';

export default function ExampleAvatar() {
  return (
    <div style={{ display: 'flex', gap: '1rem' }}>
      <Avatar.Root className={styles.Root}>
        <Avatar.Image
          src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
          width="48"
          height="48"
          className={styles.Image}
        />
        <Avatar.Fallback delay={600} className={styles.Fallback}>
          LT
        </Avatar.Fallback>
      </Avatar.Root>
      <Avatar.Root className={styles.Root}>LT</Avatar.Root>
    </div>
  );
}

Anatomy

Import the component and assemble its parts:

Anatomy

import { Avatar } from '@base-ui/react/avatar';

<Avatar.Root>
  <Avatar.Image src="" />
  <Avatar.Fallback>LT</Avatar.Fallback>
</Avatar.Root>

Optimized and lazy-loaded images

By default, <Avatar.Image> preloads src and renders the image only once it has loaded. This doesn’t compose with image optimizers such as next/image, which serve a different URL than the raw src, or with loading="lazy".

Add the keepMounted prop to render the image element right away and let it load in place. Only the image that is actually displayed is requested:

Using next/image

import Image from 'next/image';

<Avatar.Root>
  <Avatar.Fallback>LT</Avatar.Fallback>
  <Avatar.Image keepMounted render={<Image src="/avatar.png" width={32} height={32} alt="" />} />
</Avatar.Root>

Stacking

With keepMounted, the image and the fallback are both present until the image loads. The image is hidden from assistive technology until then, so the fallback provides the accessible name on its own.

Stack the two in the same box, and place <Avatar.Image> after <Avatar.Fallback>. Both are positioned, so whichever comes later in the DOM paints on top. The fallback then shows through until the image covers it.

A loading image paints nothing, so the fallback shows through on its own. An image that failed to load paints a broken-image icon on top of it. Hide the image in either state with the data-loading and data-error attributes:

Stacked image and fallback

.Root {
  position: relative;
}

.Image,
.Fallback {
  position: absolute;
  inset: 0;
}

.Image[data-loading],
.Image[data-error] {
  visibility: hidden;
}

Avoid display: none here: an element without a box never intersects the viewport, so loading="lazy" would never fetch the image. visibility and opacity both keep lazy loading working.

Server rendering

With keepMounted, the image is part of the server-rendered HTML and starts loading before hydration. So is the fallback, which stays visible until hydration resolves the loading status. A cached image is displayed immediately, without an enter animation.

API reference

Root

Displays a user’s profile picture, initials, or fallback icon. Renders a <span> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Avatar.Root.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Avatar.Root.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Avatar.Root.State, ) => ReactElement) | undefined

Avatar.Root.PropsHide

Re-Export of Root props as AvatarRootProps

Avatar.Root.StateHide

type AvatarRootState = {
  /** The image loading status. */
  imageLoadingStatus: ImageLoadingStatus;
}

Image

The image to be displayed in the avatar. Renders an <img> element.

onLoadingStatusChangefunction—

Name: onLoadingStatusChange
Description: Callback fired when the loading status changes.
Type: ((status: ImageLoadingStatus) => void) | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Avatar.Image.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Avatar.Image.State, ) => React.CSSProperties | undefined) | undefined

keepMountedbooleanfalse

Name: keepMounted
Description: Whether the image element stays mounted and loads in place instead of being preloaded. Supports loading="lazy" and optimized image components such as next/image.
Type: boolean | undefined
Default: false

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: React.DetailedHTMLProps< React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement >, state: Avatar.Image.State, ) => ReactElement) | undefined

data-error

Present when the image failed to load.

data-loading

Present while the image is loading.

data-starting-style

Present when the image begins animating in.

data-ending-style

Present when the image is animating out.

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

Avatar.Image.PropsHide

Re-Export of Image props as AvatarImageProps

Avatar.Image.StateHide

type AvatarImageState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** The image loading status. */
  imageLoadingStatus: ImageLoadingStatus;
}

Fallback

Rendered when the image fails to load or when no image is provided. Renders a <span> element.

delaynumber0

Name: delay
Description: How long to wait before showing the fallback. Specified in milliseconds.
Type: number | undefined
Default: 0

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Avatar.Fallback.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Avatar.Fallback.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Avatar.Fallback.State, ) => ReactElement) | undefined

Avatar.Fallback.PropsHide

Re-Export of Fallback props as AvatarFallbackProps

Avatar.Fallback.StateHide

type AvatarFallbackState = {
  /** The image loading status. */
  imageLoadingStatus: ImageLoadingStatus;
}

Additional types

ImageLoadingStatusHide

type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error'