Shadcn Avatar
React avatar component for user profiles with automatic image fallbacks. Built with TypeScript and Tailwind CSS for Next.js using Radix UI.
Avatar images not loading?
Join our Discord community for help from other developers.
Ever had a user upload a 15MB vacation photo as their profile picture? Or watched your app display those awful gray silhouettes when images fail to load? Yeah, avatars seem simple until they're not. This shadcn/ui component handles all the edge cases so you don't have to.
User avatar
Standard profile display with automatic fallback:
Built on Radix UI's Avatar primitive with proper loading states and TypeScript types. Styled with Tailwind CSS because inline styles are gross.
npx shadcn@latest add avatarWhy avatars actually build trust
Here's the thing—avatars aren't just decorative circles with pictures. They're trust signals. When users see a real photo (or even personalized initials), they feel like they're interacting with actual humans, not a faceless system.
Think about it: would you rather leave a comment for "User12345" or someone with a profile picture? Even when images fail to load, showing initials like "JD" feels more personal than a generic icon. It's the difference between a conversation and a form submission.
This free shadcn component handles the messy parts—image loading, error states, fallbacks—while you focus on building features. Whether you're building comment sections, chat apps, or user lists in your JavaScript projects, avatars that actually work make the whole thing feel less janky.
Common avatar patterns you'll actually use
Avatar sizes
From tiny inline mentions to large profile headers:
Avatar fallbacks
Smart fallbacks when images aren't available:
Avatar groups
Team displays with overlapping layouts:
Features
This free open source avatar component includes everything you need:
- TypeScript-first design - Full type safety with loading state callbacks
- Tailwind CSS utilities - Size and style with utility classes, not props
- Smart fallbacks - Shows initials, icons, or whatever you want
- Loading state management - No flash of missing content during image load
- Radix UI foundation - Battle-tested primitive with accessibility built-in
- Flexible shapes - Round, square, or custom shapes with simple classes
- Group-ready - Built-in support for overlapping avatar stacks
API Reference
Avatar
The root container that manages image loading states.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | Additional CSS classes for styling |
children | React.ReactNode | - | AvatarImage and AvatarFallback components |
asChild | boolean | false | Render as child component using Radix UI Slot |
AvatarImage
The image element with automatic loading state management.
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | - | Image source URL |
alt | string | - | Alternative text for accessibility |
className | string | - | Additional CSS classes for styling |
onLoadingStatusChange | (status: "idle" | "loading" | "loaded" | "error") => void | - | Callback when loading state changes |
asChild | boolean | false | Render as child component using Radix UI Slot |
AvatarFallback
Displays when the image hasn't loaded or failed to load.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | Additional CSS classes for styling |
delayMs | number | 0 | Delay before showing fallback to prevent flashing |
children | React.ReactNode | - | Fallback content (text, icons, or components) |
asChild | boolean | false | Render as child component using Radix UI Slot |
Common Size Classes
| Size | Class | Use Case |
|---|---|---|
| Extra Small | size-6 | Inline mentions, compact lists |
| Small | size-8 | Comments, chat messages |
| Medium | size-10 | Navigation menus, cards |
| Large | size-14 | Profile headers, user cards |
| Extra Large | size-20 | Profile pages, hero sections |
Loading States
| State | Description | When it occurs |
|---|---|---|
idle | Initial state before loading | Component mounts |
loading | Image is being fetched | After src is provided |
loaded | Image successfully loaded | Image loads without errors |
error | Image failed to load | Network error or invalid URL |
Production tips
Optimize those image sizes. This free shadcn/ui avatar works great, but don't make users download 4K photos for tiny profile pics. Use image CDNs that serve appropriately sized images based on display dimensions.
Set delayMs on fallbacks. Add a 600ms delay before showing fallbacks to prevent flashing during normal network conditions. Your React avatar won't have that annoying flash when images load normally.
Generate initials intelligently. Don't just grab the first two letters. Parse names properly—"John Smith" becomes "JS", not "JO". This TypeScript component accepts any fallback content, so handle edge cases like single names or special characters.
Use status indicators sparingly. That green "online" ring looks cool, but only add it where users actually care about presence. Too many indicators create visual noise in your Next.js applications.
Test with broken images. Your open source shadcn avatar should look good even when half the images fail to load. Disable images in dev tools and make sure your fallbacks are presentable.
Integration with other components
Avatars work brilliantly with DropdownMenu components for user account menus in your React applications. Combine with Badge components to show user roles or status indicators next to profile pictures.
For loading states, throw in Skeleton components while user data loads. This open source pattern stops the page from jumping around. When building user cards, avatars naturally fit within Card components to create rich profile displays.
Questions you might have
Shadcn Aspect Ratio
React aspect ratio component for consistent image and video proportions. Built with TypeScript and Tailwind CSS for Next.js applications with responsive design.
Shadcn Badge
React badge component for status indicators, notification counts, and labels. Built with TypeScript and Tailwind CSS for Next.js using CVA variants.