Documentation Index
Fetch the complete documentation index at: https://mintlify.com/mui/base-ui/llms.txt
Use this file to discover all available pages before exploring further.
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 { 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
The root container element that manages the avatar state.
Props:
- Renders a
<span> element
- Accepts all standard HTML span attributes
The image element to display in the avatar.
Props:
src (string): The image source URLalt (string): Alternative text for the imageonLoadingStatusChange (function): Callback fired when loading status changesreferrerPolicy (string): Referrer policy for the imagecrossOrigin (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;
}
<Avatar.Root className="inline-flex items-center justify-center w-12 h-12 rounded-full overflow-hidden bg-gray-200">
<Avatar.Image
className="w-full h-full object-cover"
src="/avatar.jpg"
alt="User"
/>
<Avatar.Fallback className="text-lg font-semibold text-gray-700">
JD
</Avatar.Fallback>
</Avatar.Root>
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>
);
}