Documentation Index
Fetch the complete documentation index at: https://mintlify.com/radix-ui/primitives/llms.txt
Use this file to discover all available pages before exploring further.
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.
Alternative text description of the image.
onLoadingStatusChange
(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.
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.