---
title: Avatar
description: An image element with a fallback for representing the user.
icon: user
author:
  name: shadcn
  url: https://github.com/shadcn
mode: wide
---

<PoweredBy
  packages={[
    { name: 'Base UI', url: 'https://base-ui.com/react/components/avatar' },
    { name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/avatar' },
  ]}
/>

### Installation

```package-install
npx shadcn@latest add @redpanda/avatar
```

<ComponentPreview name="avatar-demo" description="Default avatar with image and fallback initials." />

### 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.

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

### Sizes

<ComponentPreview
  name="avatar-sizes-demo"
  description="Resize by overriding the root class — from `size-6` (xs) up to `size-16` (xl)."
/>

### Fallback only

<ComponentPreview
  name="avatar-fallback-demo"
  description="No image source — rely entirely on `AvatarFallback` (initials, icons, or placeholder text)."
/>

### Fallback variations

<ComponentPreview
  name="avatar-fallback-only-demo"
  description="Avatar rendering initials or icon fallback when no image is provided."
/>

### With status dot

<ComponentPreview
  name="avatar-with-status-dot-demo"
  description="Avatar with a composed presence status dot (online/away/busy)."
/>

### With notification badge

<ComponentPreview
  name="avatar-with-notification-badge-demo"
  description="Avatar with a numeric notification badge overlaid on the corner."
/>

## Usage

### Basic Example

```tsx lineNumbers
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

```tsx lineNumbers
// 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

```tsx lineNumbers
// 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

```tsx lineNumbers
<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:

```mermaid
graph TD;
    A[❓ Need to show user representation?] --> B{Have user image?};

    B -->|Yes, reliable| C[✅ Use Avatar with AvatarImage];
    B -->|Yes, unreliable| D[✅ Use Avatar with AvatarImage + AvatarFallback];
    B -->|No| E[✅ Use Avatar with AvatarFallback only];

    F{Multiple users to show?} --> G[⚠️ Use AvatarGroup component];
    F --> H[✅ Use single Avatar];

    I{Need different sizes?} --> J[✅ Apply size classes to Avatar];
    I --> K[✅ Use default size];

    L{Need status indicators?} --> M[✅ Add status elements as siblings];
    L --> N[✅ Use plain Avatar];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class C,D,E,H,J,K,M,N recommended;
    class G discouraged;
    class A,B,F,I,L decision;
```

**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 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

<div className="flex flex-row gap-x-3">
  <ExternalLink href="https://base-ui.com/react/components/avatar" text="Docs" />
  <ExternalLink href="https://base-ui.com/react/components/avatar#api-reference" text="API Reference" />
</div>

## 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](https://base-ui.com/react/components/avatar) for the avatar component.
- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/avatar) for the avatar style.