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

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

## Preview

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

## Installation

<CodeTabs>

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

<TabsPanel value="cli">

```bash
npx @olyx/cli@latest add 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>
```

## API Reference

### Avatar

Root component. Styled wrapper for `Avatar.Root` from Base UI.

| Prop    | Type                       | Default    |
| ------- | -------------------------- | ---------- |
| `size`  | `number`                   | `40`       |
| `shape` | `"circle" \| "square"`     | `"circle"` |

### AvatarImage

Image element for the avatar. Styled wrapper for `Avatar.Image` from Base UI.

### AvatarFallback

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

### AvatarBadge

Status indicator badge overlaying the avatar.

| Prop     | Type                                           | Default    |
| -------- | ---------------------------------------------- | ---------- |
| `status` | `"online" \| "offline" \| "busy" \| "away"`    | `"online"` |

### AvatarGroup

Container for displaying multiple avatars with overlap styling.

### AvatarGroupCount

Count indicator showing additional users not displayed. Must be used inside an `Avatar` component within `AvatarGroup`.

## Examples

### Fallback Only

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

### With Status

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

### Sizes

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

### Shapes

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

### Group

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