---
title: Avatar
description: An image element with a fallback for representing the user.

links:
  doc: https://base-ui.com/react/components/avatar#api-reference
---

<ComponentPreview name="p-avatar-1" />

## Installation

<CodeTabs>

<TabsList>
  <TabsTab value="cli">CLI</TabsTab>
  <TabsTab value="manual">Manual</TabsTab>
</TabsList>

<TabsPanel value="cli">

```bash
npx shadcn@latest add @coss/avatar
```

</TabsPanel>

<TabsPanel value="manual">

<Steps>

<Step>Install the following dependencies:</Step>

```bash
npm install @base-ui/react
```

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="avatar" title="components/ui/avatar.tsx" />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsPanel>

</CodeTabs>

## Usage

```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
```

```tsx
<Avatar>
  <AvatarImage src="/avatars/01.png" alt="User avatar" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
```

Use `keepMounted` when the image relies on native lazy loading or an optimized image component. The fallback remains visible while the image loads or if it fails:

```tsx
<Avatar>
  <AvatarImage
    src="/avatars/01.png"
    alt="User avatar"
    loading="lazy"
    keepMounted
  />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
```

## API Reference

### Avatar

Root component. Styled wrapper for `Avatar.Root` from Base UI with default size of 32px (8 units) and rounded-full styling.

### AvatarImage

Image element for the avatar. Styled wrapper for `Avatar.Image` from Base UI with support for `keepMounted` images.

### AvatarFallback

Fallback content displayed when the image fails to load. Styled wrapper for `Avatar.Fallback` from Base UI with muted background.

## Examples

### Fallback Only

<ComponentPreview name="p-avatar-2" />

### Different Sizes

<ComponentPreview name="p-avatar-3" />

### Different Radius

<ComponentPreview name="p-avatar-4" />

### Group Avatars

<ComponentPreview name="p-avatar-5" />