Navigation: [/sitemap.md](/sitemap.md)

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

```astro live props={{ name: 'avatar' }}
---
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarImage,
} from "@/components/ui/avatar"
import avatar from "@/assets/avatar-sil-veltman.webp"
---

<div class="flex flex-row flex-wrap items-center gap-12">
  <Avatar>
    <AvatarImage src={avatar} alt="@silveltm" />
    <AvatarFallback>SV</AvatarFallback>
  </Avatar>
  <Avatar size="lg">
    <AvatarImage src={avatar} alt="@silveltm" />
    <AvatarFallback>SV</AvatarFallback>
  </Avatar>
  <Avatar size="lg">
    <AvatarFallback>FD</AvatarFallback>
  </Avatar>
  <AvatarGroup class="*:grayscale">
    <Avatar>
      <AvatarImage src={avatar} alt="@silveltm" />
      <AvatarFallback>SV</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarImage src={avatar} alt="@silveltm" />
      <AvatarFallback>SV</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarImage src={avatar} alt="@silveltm" />
      <AvatarFallback>SV</AvatarFallback>
    </Avatar>
  </AvatarGroup>
</div>
```

## Installation

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

## Usage

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

```astro
<Avatar>
  <AvatarImage src="/avatar.jpg" alt="Team member" />
  <AvatarFallback>TM</AvatarFallback>
</Avatar>
```

## Composition

Use the following composition to build an `Avatar`:

```text
Avatar
├── AvatarImage
├── AvatarFallback
└── AvatarBadge
```

Use the following composition to build an `AvatarGroup`:

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

## Examples

### Fallback

Use `AvatarFallback` when an image is unavailable or intentionally omitted.

```astro live
---
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
---

<Avatar size="lg">
  <AvatarFallback>FD</AvatarFallback>
</Avatar>
```

### Group

Use `AvatarGroup` when you need overlapping participant or collaborator lists.

```astro live
---
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from "@/components/ui/avatar"
import avatar from "@/assets/avatar-sil-veltman.webp"
---

<AvatarGroup>
  <Avatar>
    <AvatarImage src={avatar} alt="Sil Veltman" />
    <AvatarFallback>SV</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src={avatar} alt="Teammate" />
    <AvatarFallback>TM</AvatarFallback>
  </Avatar>
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
```

## Notes

- Always include `AvatarFallback` so initials or placeholder content remain
  visible when the image fails to load.
- Use size variants on `Avatar` instead of custom width and height classes when
  possible.

## API Reference

See the [GitHub source code](https://github.com/fulldotdev/ui/tree/main/src/components/ui/avatar) for more information on props.