Skip to main content

​
Avatar

The Avatar component displays a user’s profile picture, initials, or fallback icon. It automatically handles image loading states and provides a fallback when the image fails to load or is unavailable.

​
Import

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

​
Anatomy

The Avatar component consists of three parts:
  • <Avatar.Root> - The container element
  • <Avatar.Image> - The profile image
  • <Avatar.Fallback> - Content shown when the image is unavailable
<Avatar.Root>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>

​
Basic Usage

function MyAvatar() {
  return (
    <Avatar.Root>
      <Avatar.Image 
        src="https://i.pravatar.cc/150?img=1" 
        alt="Jane Doe" 
      />
      <Avatar.Fallback>JD</Avatar.Fallback>
    </Avatar.Root>
  );
}

​
Key Features

  • Automatic fallback: Shows fallback content when the image fails to load
  • Loading states: Tracks image loading status (idle, loading, loaded, error)
  • Delayed fallback: Optionally delay the fallback display
  • Accessible: Proper image alt text support
  • Unstyled: Full control over styling

​
Component Props

​
Root

The root container element that manages the avatar state. Props:
  • Renders a <span> element
  • Accepts all standard HTML span attributes

​
Image

The image element to display in the avatar. Props:
  • src (string): The image source URL
  • alt (string): Alternative text for the image
  • onLoadingStatusChange (function): Callback fired when loading status changes
  • referrerPolicy (string): Referrer policy for the image
  • crossOrigin (string): CORS settings for the image
  • Renders an <img> element

​
Fallback

Content displayed when the image is unavailable or fails to load. Props:
  • delay (number): How long to wait before showing the fallback, in milliseconds
  • Renders a <span> element

​
Styling

<Avatar.Root className="avatar-root">
  <Avatar.Image 
    className="avatar-image"
    src="/avatar.jpg" 
    alt="User" 
  />
  <Avatar.Fallback className="avatar-fallback">
    JD
  </Avatar.Fallback>
</Avatar.Root>

.avatar-root {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 48px;
  height: 48px;
  border-radius: 50%;
  overflow: hidden;
  background-color: #e0e0e0;
}

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

.avatar-fallback {
  font-size: 18px;
  font-weight: 600;
  color: #333;
}

​
Common Patterns

​
With Delayed Fallback

Delay showing the fallback to avoid flashing content during quick loads: 
<Avatar.Root>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <Avatar.Fallback delay={300}>
    JD
  </Avatar.Fallback>
</Avatar.Root>

​
Different Sizes

function AvatarSizes() {
  return (
    <div style={{ display: 'flex', gap: '1rem' }}>
      {/* Small */}
      <Avatar.Root style={{ width: 32, height: 32 }}>
        <Avatar.Image src="/avatar.jpg" alt="User" />
        <Avatar.Fallback>JD</Avatar.Fallback>
      </Avatar.Root>

      {/* Medium */}
      <Avatar.Root style={{ width: 48, height: 48 }}>
        <Avatar.Image src="/avatar.jpg" alt="User" />
        <Avatar.Fallback>JD</Avatar.Fallback>
      </Avatar.Root>

      {/* Large */}
      <Avatar.Root style={{ width: 64, height: 64 }}>
        <Avatar.Image src="/avatar.jpg" alt="User" />
        <Avatar.Fallback>JD</Avatar.Fallback>
      </Avatar.Root>
    </div>
  );
}

​
With Status Indicator

<Avatar.Root style={{ position: 'relative' }}>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <Avatar.Fallback>JD</Avatar.Fallback>
  <span
    style={{
      position: 'absolute',
      bottom: 0,
      right: 0,
      width: 12,
      height: 12,
      borderRadius: '50%',
      backgroundColor: '#22c55e',
      border: '2px solid white',
    }}
  />
</Avatar.Root>

​
Tracking Loading Status

function AvatarWithStatus() {
  const [status, setStatus] = React.useState('idle');

  return (
    <div>
      <Avatar.Root>
        <Avatar.Image 
          src="/avatar.jpg" 
          alt="User"
          onLoadingStatusChange={(status) => setStatus(status)}
        />
        <Avatar.Fallback>JD</Avatar.Fallback>
      </Avatar.Root>
      <p>Status: {status}</p>
    </div>
  );
}