# Avatar

An image element with a fallback for representing the user.

> Every page: https://constella.aayush.cv/llms.txt

```tsx
<Avatar>
  <AvatarImage alt="@aayushbtw" src="/avatars/aayushbtw.png" />
  <AvatarFallback>AY</AvatarFallback>
</Avatar>
```

## Installation

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

## Usage

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

```tsx
<Avatar>
  <AvatarImage alt="@aayushbtw" src="/avatars/aayushbtw.png" />
  <AvatarFallback>AY</AvatarFallback>
</Avatar>
```

## Composition

```
AvatarGroup
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarBadge
└── AvatarGroupCount
```

## Size

Use the `size` prop to match the controls beside it.

| Size      | Diameter |
| --------- | -------- |
| `sm`      | 24px     |
| `default` | 32px     |
| `lg`      | 36px     |

```tsx
<Avatar size="sm">
  <AvatarImage alt="@aayushbtw" src="/avatars/aayushbtw.png" />
  <AvatarFallback>AY</AvatarFallback>
</Avatar>
```

## Corners

Use `corners="rounded"` for a logo or an app icon. Avatar groups take the default `pill`.

```tsx
<Avatar corners="rounded">
  <AvatarImage alt="shadcn" src="/avatars/shadcn.png" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>
```

## Fallback

`AvatarFallback` shows while the image loads, and stays when it fails.

```tsx
<Avatar>
  <AvatarFallback>AY</AvatarFallback>
</Avatar>
```

## Badge

Use `AvatarBadge` for a dot on the avatar's corner. Its `presence` prop colors it and names it for screen readers; pass `aria-label` to rename it.

| Status    | Color | Label     |
| --------- | ----- | --------- |
| `online`  | Green | "Online"  |
| `away`    | Amber | "Away"    |
| `busy`    | Red   | "Busy"    |
| `offline` | Gray  | "Offline" |

```tsx
<Avatar>
  <AvatarImage alt="@aayushbtw" src="/avatars/aayushbtw.png" />
  <AvatarFallback>AY</AvatarFallback>
  <AvatarBadge presence="busy" />
</Avatar>
```

### With Icon

Put an icon inside `AvatarBadge`, with or without a `presence`.

```tsx
<Avatar>
  <AvatarImage alt="@aayushbtw" src="/avatars/aayushbtw.png" />
  <AvatarFallback>AY</AvatarFallback>
  <AvatarBadge presence="online">
    <HugeiconsIcon icon={Tick02Icon} size={sizes.iconXxs} />
  </AvatarBadge>
</Avatar>
```

## Avatar Group

Use `AvatarGroup` to overlap avatars.

```tsx
<AvatarGroup>
  <Avatar>
    <AvatarImage alt="@shadcn" src="/avatars/shadcn.png" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage alt="@evilrabbit" src="/avatars/evilrabbit.png" />
    <AvatarFallback>ER</AvatarFallback>
  </Avatar>
</AvatarGroup>
```

### Count

Use `AvatarGroupCount` for the avatars left out.

```tsx
<AvatarGroup>
  <Avatar>
    <AvatarImage alt="@shadcn" src="/avatars/shadcn.png" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage alt="@evilrabbit" src="/avatars/evilrabbit.png" />
    <AvatarFallback>ER</AvatarFallback>
  </Avatar>
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
```

### With Icon

Put an icon inside `AvatarGroupCount` in place of the number.

```tsx
<AvatarGroup>
  <Avatar>
    <AvatarImage alt="@shadcn" src="/avatars/shadcn.png" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <AvatarGroupCount>
    <HugeiconsIcon icon={Add01Icon} size={sizes.icon} />
  </AvatarGroupCount>
</AvatarGroup>
```

## Dropdown Menu

Render an avatar inside a [Dropdown Menu](https://constella.aayush.cv/docs/components/dropdown-menu/index.md) trigger for an account menu.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger
    render={<Button aria-label="Account" size="icon" variant="ghost" />}
  >
    <Avatar>
      <AvatarImage alt="@aayushbtw" src="/avatars/aayushbtw.png" />
      <AvatarFallback>AY</AvatarFallback>
    </Avatar>
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Profile</DropdownMenuItem>
    <DropdownMenuItem color="danger">Log out</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## API Reference

`Avatar` takes `size` (`"sm"`, `"default"` or `"lg"`) and `corners` (`"pill"` or `"rounded"`). `AvatarBadge` takes `presence`. Every part takes `sx`, applied last. For the rest, see [Base UI Avatar](https://base-ui.com/react/components/avatar).