Avatar

Overview

Avatar is an image element with a fallback for representing a user or entity. It automatically handles loading states and can show initials or an icon when an image is unavailable.

Features

Automatic and manual control over when the image renders
Fallback part accepts any children
Optionally delay fallback rendering to avoid content flashing

Installation

npm install @radix-ui/react-avatar

Anatomy

import * as Avatar from '@radix-ui/react-avatar';

export default () => (
  <Avatar.Root>
    <Avatar.Image />
    <Avatar.Fallback />
  </Avatar.Root>
)

API Reference

Root

Contains all the parts of an avatar.

Image

The image to render. By default it will only render when it has loaded.

string

The source of the image.

string

Alternative text description of the image.

(status: 'idle' | 'loading' | 'loaded' | 'error') => void

Callback fired when the loading status changes.

Fallback

An element that renders when the image hasn’t loaded. This means whilst it’s loading, or if there was an error.

number

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

Examples

Basic Usage

import * as Avatar from '@radix-ui/react-avatar';

export default () => (
  <Avatar.Root
    style={{
      display: 'inline-flex',
      alignItems: 'center',
      justifyContent: 'center',
      verticalAlign: 'middle',
      width: 45,
      height: 45,
      borderRadius: '100%',
      overflow: 'hidden',
    }}
  >
    <Avatar.Image
      src="https://images.unsplash.com/photo-1492633423870-43d1cd2775eb"
      alt="John Doe"
      style={{ width: '100%', height: '100%', objectFit: 'cover' }}
    />
    <Avatar.Fallback
      style={{
        width: '100%',
        height: '100%',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        backgroundColor: 'lightgray',
        color: 'white',
        fontSize: 15,
        fontWeight: 500,
      }}
    >
      JD
    </Avatar.Fallback>
  </Avatar.Root>
);

Delayed Fallback

import * as Avatar from '@radix-ui/react-avatar';

export default () => (
  <Avatar.Root>
    <Avatar.Image
      src="https://images.unsplash.com/photo-1492633423870-43d1cd2775eb"
      alt="John Doe"
    />
    <Avatar.Fallback delayMs={600}>
      JD
    </Avatar.Fallback>
  </Avatar.Root>
);

The delayMs prop is useful for preventing the fallback from flashing on screen for users with fast connections.

With Loading Status

import * as Avatar from '@radix-ui/react-avatar';
import { useState } from 'react';

export default () => {
  const [status, setStatus] = useState('idle');

  return (
    <div>
      <Avatar.Root>
        <Avatar.Image
          src="https://images.unsplash.com/photo-1492633423870-43d1cd2775eb"
          alt="John Doe"
          onLoadingStatusChange={setStatus}
        />
        <Avatar.Fallback>JD</Avatar.Fallback>
      </Avatar.Root>
      <p>Image status: {status}</p>
    </div>
  );
};

Accessibility

Adheres to the img role requirements. The Image component should always have alt text to describe the image for screen reader users.

Overlays

Navigation

Forms

Layout

Data Display

Utilities

Overview

Features

Installation

Anatomy

API Reference

Root

Image

Fallback

Examples

Basic Usage

Delayed Fallback

With Loading Status

Accessibility

​Overview

​Features

​Installation

​Anatomy

​API Reference

​Root

​Image

​Fallback

​Examples

​Basic Usage

​Delayed Fallback

​With Loading Status

​Accessibility

Overview

Features

Installation

Anatomy

API Reference

Root

Image

Fallback

Examples

Basic Usage

Delayed Fallback

With Loading Status

Accessibility