# Avatar

A circular user image with fallback, badge, and stacking group.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="avatar" />

<ComponentPreview name="avatar" title="avatar.tsx" previewClassName="h-auto p-10">
<Component />
</ComponentPreview>

Avatar renders a circular user image with a text fallback when the image fails to load or is missing. A small composable API covers badges, groups, and counts.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add avatar
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
```

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

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

<Step>
Copy the demo avatars into your project.
</Step>

<div className="text-sm text-muted-foreground">

  The CLI copies five AVIF avatars into `public/avatars/`:
  `female-l-1`, `female-l-2`, `female-l-3`, `male-l`, `male-r`.
  The `-l` suffix faces left, `-r` faces right. Use one direction
  consistently within a single row or group.

</div>

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

## Usage [#usage]

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

```tsx title="avatar.tsx"
<Avatar>
  <AvatarImage src="/avatars/me.avif" />
  <AvatarFallback>ME</AvatarFallback>
</Avatar>
```

Pass `grayscale` through `className` to desaturate. Demo assets follow a `-l` (facing left) and `-r` (facing right) convention — pick one per row.

## Group [#group]

**AvatarGroup** overlaps avatars with a 2px background ring between each one, keeping the stack readable. Place **AvatarGroupCount** as the last child to show how many more are hidden, and **AvatarBadge** inside an **Avatar** to indicate presence. Swap to right-to-left stacking with `className="flex-row-reverse"`.

<ComponentPreview name="avatar-group" title="avatar-group.tsx" src="examples/avatar-group.tsx">
<a />
</ComponentPreview>

### With count [#with-count]

<ComponentPreview name="avatar-count" title="avatar-count.tsx" src="examples/avatar-count.tsx">
<r />
</ComponentPreview>

```tsx title="avatargroup.tsx"
<AvatarGroup>
  <Avatar>
    <AvatarImage src="/avatars/anna.avif" />
    <AvatarFallback>AN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/avatars/sara.avif" />
    <AvatarFallback>SA</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/avatars/liv.avif" />
    <AvatarFallback>LV</AvatarFallback>
  </Avatar>
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
```

### With badge [#with-badge]

Place **AvatarBadge** as the last child of an **Avatar**. Its position is automatic (bottom-right). Put the status in `sr-only` text inside the badge so screen readers announce it.

<ComponentPreview name="avatar-badge-group" title="avatar-badge-group.tsx" src="examples/avatar-badge-group.tsx">
<l />
</ComponentPreview>

## With image and fallback [#with-image-and-fallback]

Pass `src` on **AvatarImage**. **AvatarFallback** renders while the image loads, when it fails, or when no image is supplied. A failed load auto-styles the fallback with the destructive token. Without `AvatarImage`, the fallback keeps the muted surface.

<ComponentPreview name="avatar-image-fallback" title="avatar-image-fallback.tsx" src="examples/avatar-image-fallback.tsx" previewClassName="h-auto">
<h />
</ComponentPreview>

## Sizes [#sizes]

Three sizes are available via the `size` prop. The default is 32px, `sm` is 24px, `lg` is 40px. Pass `size` on each **Avatar** in a group and the trailing **AvatarGroupCount** follows.

<ComponentPreview name="avatar-sizes" title="avatar-sizes.tsx" src="examples/avatar-sizes.tsx" previewClassName="h-auto">
<d />
</ComponentPreview>

## In context [#in-context]

Pair **Avatar** with [Message](/docs/components/message) and [Bubble](/docs/components/bubble) for a chat layout.

<ComponentPreview name="avatar-context" title="avatar-context.tsx" src="examples/avatar-context.tsx" previewClassName="h-auto">
<c />
</ComponentPreview>

## API Reference [#api-reference]

### Avatar [#avatar]

<PropsTable rows={[{"name":"size","type":"sm | default | lg","default":"default","description":"Controls the diameter of the avatar (24px / 32px / 40px)."}]} />

### AvatarImage [#avatarimage]

Renders the avatar image. Requires `src` and `alt`. Applies `object-cover` and `rounded-full`. Hidden until the image finishes loading, so the fallback shows first.

### AvatarFallback [#avatarfallback]

Renders children when the image is missing, still loading, or fails. Use 2–3 character initials.

### AvatarBadge [#avatarbadge]

Extends `React.ComponentProps<"span">`. Positioned absolutely at the bottom-right. Pass a background color with `className` (e.g., `bg-green-600`).

### AvatarGroup / AvatarGroupCount [#avatargroup--avatargroupcount]

Extend `React.ComponentProps<"div">`. Group applies `-space-x-2` and a 2px background ring per avatar. Count inherits the size of the group's avatars via `has-data-[size=lg]`.

## Accessibility [#accessibility]

- Always pass `alt` on **AvatarImage** — describe the person, not the file. Use `@username` for handles.
- **AvatarFallback** initials act as a visual label but are not read as a name. If the avatar has semantic meaning, wrap the group in a container with `aria-label`.
- **AvatarBadge** is decorative. Convey the status in text when it matters (e.g., "Online").
- **AvatarGroup** should have an accessible label like `aria-label="3 participants"` when it summarizes a list.

## Best Practices [#best-practices]

- **Always include a fallback.** `AvatarFallback` renders when the image fails or is missing.
- **Size by context.** 24px in lists, 40px in headers, 64px in profiles.
- **Add an accessible name.** Wrap in a button with `aria-label` when clickable.
- **Do not rely on the image alone.** Pair with the user's name or a tooltip.