Avatar

An image element with a fallback for representing the user.

Powered by

Base UIShadcn UI

Installation

npx shadcn@latest add @redpanda/avatar

pnpm dlx shadcn@latest add @redpanda/avatar

yarn dlx shadcn@latest add @redpanda/avatar

bunx shadcn@latest add @redpanda/avatar

nubx shadcn@latest add @redpanda/avatar

aube dlx shadcn@latest add @redpanda/avatar

Shape

Use shape="square" for rounded-square avatars. The default, shape="round", remains circular. The image and fallback inherit the root radius, so loading an image does not change the shape.

<Avatar shape="square">  <AvatarImage src="/user.jpg" alt="Alex" />  <AvatarFallback>AL</AvatarFallback></Avatar>

Sizes

Fallback only

Fallback variations

With status dot

With notification badge

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 tone="brand">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-success-strong ring-2 ring-background" /></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-warning-strong ring-2 ring-background" /></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 successfully2. Show AvatarFallback if image fails or while loading3. AvatarFallback always rendered but hidden when image loads

Component Hierarchy:

1. Avatar (Root): Container with circular shape and sizing
2. AvatarImage: Primary image that loads asynchronously
3. 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)

Owned identity appearance

• AvatarFallback tone="default" preserves the neutral fallback. primary, success, and brand own their corresponding fill/foreground pairs; do not restyle the fallback’s background or text. A tone is identity appearance, not an accessible online/offline status. Use a separately named status indicator when needed.
• AvatarImage monochrome desaturates only the photo. Its fallback and unrelated status indicators stay unchanged.
• The static AvatarGroup exported from avatar accepts monochrome to desaturate each direct avatar subtree, including fallback content. This is deliberately different from photo-only monochrome.
• Avatar frame="group" adds the owned background-colored separator border for overlapping identity images. The default frame="none" leaves existing geometry unchanged.

Props

Accessibility

• Always provide alt on AvatarImage — either the user’s display name for identification, or alt="" when the avatar is purely decorative next to a visible name.
• AvatarFallback is 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 — Avatar is 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.