Avatar
An image element with a fallback for representing the user.
Made by shadcnInstallation
Loading component...
Sizes
Loading component...
Fallback only
Loading component...
Fallback variations
Loading component...
With status dot
Loading component...
With notification badge
Loading component...
Usage
Basic Example
import { Avatar, AvatarFallback, AvatarImage } from "@/components/redpanda-ui/avatar"
<Avatar>
<AvatarImage src="https://github.com/malinskibeniamin.png" alt="@malinskibeniamin" />
<AvatarFallback>BM</AvatarFallback>
</Avatar>Different Sizes
// Small avatar
<Avatar className="h-6 w-6">
<AvatarImage src="/user-small.jpg" alt="User" />
<AvatarFallback className="text-xs">U</AvatarFallback>
</Avatar>
// Default avatar (32px)
<Avatar>
<AvatarImage src="/user-default.jpg" alt="User" />
<AvatarFallback>JD</AvatarFallback>
</Avatar>
// Large avatar
<Avatar className="h-12 w-12">
<AvatarImage src="/user-large.jpg" alt="User" />
<AvatarFallback>JD</AvatarFallback>
</Avatar>
// Extra large avatar
<Avatar className="h-16 w-16">
<AvatarImage src="/user-xl.jpg" alt="User" />
<AvatarFallback className="text-lg">JD</AvatarFallback>
</Avatar>Fallback Examples
// Text initials
<Avatar>
<AvatarImage src="/broken-link.jpg" alt="User" />
<AvatarFallback>JD</AvatarFallback>
</Avatar>
// Icon fallback
<Avatar>
<AvatarImage src="/broken-link.jpg" alt="User" />
<AvatarFallback>
<User className="h-4 w-4" />
</AvatarFallback>
</Avatar>
// Custom background
<Avatar>
<AvatarImage src="/broken-link.jpg" alt="User" />
<AvatarFallback className="bg-red-500 text-white">AD</AvatarFallback>
</Avatar>Status Indicators
<div className="relative">
<Avatar>
<AvatarImage src="/user.jpg" alt="User" />
<AvatarFallback>JD</AvatarFallback>
</Avatar>
{/* Online status */}
<span className="absolute bottom-0 right-0 block h-3 w-3 rounded-full bg-green-500 ring-2 ring-white" />
</div>
<div className="relative">
<Avatar>
<AvatarImage src="/user.jpg" alt="User" />
<AvatarFallback>JD</AvatarFallback>
</Avatar>
{/* Away status */}
<span className="absolute bottom-0 right-0 block h-3 w-3 rounded-full bg-yellow-500 ring-2 ring-white" />
</div>When to use
Use Avatar to represent users or entities with their profile image and a fallback option:
Use Avatar when:
- Displaying user profile pictures in interfaces
- Showing author information in comments or posts
- Representing team members or contacts
- Building user lists or member directories
- Creating user account interfaces
Don't use Avatar when:
- Displaying non-user related images (use Image instead)
- Building image galleries (use Image)
- Showing logos or brand images (use Image)
- The image doesn't represent a person or entity
Anatomy
The Avatar component uses a layered approach with automatic fallback handling:
Avatar Container (32px × 32px by default)
┌─────────────────────────────────────────────────┐
│ Avatar Root (relative, rounded-full) │
│ ┌─────────────────────────────────────────────┐ │
│ │ AvatarImage (absolute, fills container) │ │
│ │ - Loads asynchronously │ │
│ │ - Hidden if fails to load │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ AvatarFallback (backup content) │ │
│ │ - Shows when image fails/loading │ │
│ │ - Text initials or icon │ │
│ │ - Centered content │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
Fallback Logic:
1. Show AvatarImage if available and loads successfully
2. Show AvatarFallback if image fails or while loading
3. AvatarFallback always rendered but hidden when image loadsComponent Hierarchy:
- Avatar (Root): Container with circular shape and sizing
- AvatarImage: Primary image that loads asynchronously
- AvatarFallback: Backup content (initials, icon, or text)
Key Features:
- Automatic Fallback: Seamlessly switches between image and fallback
- Loading States: Handles image loading gracefully
- Responsive: Easily customizable sizes with CSS classes
- Accessible: Proper alt text and semantic structure
- Circular Shape: Default rounded-full styling
Common Patterns:
- User Initials: First letter of first and last name
- Icon Fallback: Generic user icon when no initials available
- Custom Colors: Different background colors for visual variety
- Status Indicators: Overlay elements for online/offline status
- Size Variants: Small (24px), Default (32px), Large (48px), XL (64px)
Props
Accessibility
- Always provide
altonAvatarImage— either the user's display name for identification, oralt=""when the avatar is purely decorative next to a visible name. AvatarFallbackis rendered while the image is loading and when it fails; keep initials to 1–2 characters so they remain legible at small sizes.- No keyboard interactions —
Avataris purely presentational. Wrap it in an interactive element (link, button) if the user can click through.
Credits
- We use Base UI for the avatar component.
- We take our inspiration from Shadcn UI for the avatar style.
Recent changes
- patchv1.2.0Pin shipped dependency floors to the version we develop against. Registry items now declare ranges like `^5.1.9` (the actual installed version) instead of collapsing to `^5.0.0`, so consumers start on the known-tested b…#133
- minorv1.1.0Theme docs refresh, readability pass on semantic foregrounds, and consumer-facing Base UI regression fixes.#121
- minorv1.0.0Post-Base-UI polish. Public API unchanged.#116
- majorv1.0.0Migrate every Radix-based primitive to `@base-ui/react@^1.4.0` (Base UI).#114
- minorv0.3.0Add theme-provider component to the registry with documentation and tests. Includes playground type improvements (export RegistryItem, remove as-const boilerplate) and docs site dark mode border color fix.#109
Built by malinskibeniamin. The source code is available on GitHub.