Avatar
Data Display
User
User profile images with automatic fallbacks. Built on Radix UI for consistent behavior.
Preview
Avatar with image and fallback
CNJD
Sizes
Four avatar sizes available
SM
Small (32px)
MD
Medium (40px)
LG
Large (48px)
XL
XL (64px)
Mini Avatar
Compact rounded-square avatars for activity feeds, timelines, and data tables
Human user — indigo/teal
OC
Olivia Chen
Just now
MJ
Marcus Johnson
3 min ago
AI assistant — violet
AI
AI Assistant
Auto-assigned task
System — slate
SY
System
Task created
Fallback States
Fallback displays when image fails to load
ABJDMKTS
Use initials as fallback for a personal touch
Avatar Group
Stack avatars for team displays
Overlapping avatars
CNJDMK+5
With User Info
Common avatar + name patterns
CN
John Doe
john@example.com
AB
Alice Brown
Product Designer
Props
Avatar component API reference
| Prop | Type | Default | Description |
|---|---|---|---|
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' | Avatar size |
className | string | — | Additional CSS classes |
AvatarImage Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | — | Image source URL |
alt | string | — | Alt text for accessibility |
AvatarFallback Props
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Fallback content (usually initials) |
delayMs | number | — | Delay before showing fallback |
Usage
Import and implementation example
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'
export default function Example() { return ( <> {/* Basic avatar with image */} <Avatar> <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" /> <AvatarFallback>CN</AvatarFallback> </Avatar>
{/* Fallback only */} <Avatar> <AvatarFallback>JD</AvatarFallback> </Avatar>
{/* Different sizes */} <Avatar size="sm"><AvatarFallback>SM</AvatarFallback></Avatar> <Avatar size="md"><AvatarFallback>MD</AvatarFallback></Avatar> <Avatar size="lg"><AvatarFallback>LG</AvatarFallback></Avatar> <Avatar size="xl"><AvatarFallback>XL</AvatarFallback></Avatar>
{/* Avatar group with overlap */} <div className="flex -space-x-3"> <Avatar className="border-2 border-white"> <AvatarFallback>A</AvatarFallback> </Avatar> <Avatar className="border-2 border-white"> <AvatarFallback>B</AvatarFallback> </Avatar> <Avatar className="border-2 border-white"> <AvatarFallback>+3</AvatarFallback> </Avatar> </div>
{/* With user info */} <div className="flex items-center gap-3"> <Avatar> <AvatarImage src="/user.jpg" /> <AvatarFallback>UN</AvatarFallback> </Avatar> <div> <p className="font-medium">User Name</p> <p className="text-sm text-slate-500">user@email.com</p> </div> </div> </> )}Features
Built-in functionality
- Automatic fallback: Shows initials if image fails to load
- Four sizes: Small (32px), medium (40px), large (48px), XL (64px)
- Circular design: Full border radius for perfect circles
- Image optimization: Uses object-cover for proper scaling
- Radix UI primitives: Built on accessible components
- Fallback delay: Optional delay before showing fallback
- Composable: Combine with other components easily
- Dark mode: Full dark mode support
Accessibility
Accessibility considerations
ARIA Attributes
Uses role="img" when displaying imageAlt text passed to AvatarImageFallback is decorative when image is presentKeyboard Navigation
| Key | Action |
|---|---|
| N/A | Avatar is not focusable by default |
Notes
- Always provide alt text for profile images
- Use meaningful initials for fallback
- Consider adding aria-label for avatar groups
- Pair with visible name when possible