---
id: "packages/active-ui/avatar"
title: "Avatar"
description: "A person as a picture, or as initials when there is none, with a status badge and a group with a count."
url: "/packages/active-ui/avatar"
locale: "en"
revision: "cac823326b744923"
---

# Avatar

An avatar shows a person or an organisation as a small round picture. While the picture loads, or
when it is missing or fails, the fallback shows instead, usually the initials. It is built on Base
UI's avatar, which tracks the loading of the image.

**Example: Picture, initials, a status and a group**

Client: Runs entirely in your browser. Source: `examples/ui/avatar.tsx`.

```tsx
// apps/docs/examples/ui/avatar.tsx
'use client';

import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from '@workspace/active-ui/components/primitives/avatar';

// A portrait drawn inline, so the example loads nothing from elsewhere.
const PORTRAIT =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40"><rect width="40" height="40" fill="#c7d2fe"/><circle cx="20" cy="15" r="7" fill="#4338ca"/><path d="M6 38c2-9 8-13 14-13s12 4 14 13z" fill="#4338ca"/></svg>',
  );

// An image that cannot be decoded, as a missing photo would fail to load.
const BROKEN = 'data:image/png;base64,AAAA';

/**
 * A person as a picture, or as initials when there is no picture or it
 * fails to load. Three sizes, a status badge, and a group that ends in a
 * count of the rest.
 */
export default function AvatarExample() {
  return (
    <div className="flex flex-col items-center gap-6">
      <div className="flex items-center gap-4">
        <Avatar size="sm">
          <AvatarImage src={PORTRAIT} alt="Sam de Vries" />
          <AvatarFallback>SV</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src={PORTRAIT} alt="Sam de Vries" />
          <AvatarFallback>SV</AvatarFallback>
        </Avatar>
        <Avatar size="lg">
          <AvatarImage src={BROKEN} alt="Noor Jansen" />
          <AvatarFallback>NJ</AvatarFallback>
        </Avatar>
        <Avatar size="lg">
          <AvatarFallback>AB</AvatarFallback>
          <AvatarBadge
            className="bg-tone-success"
            role="img"
            aria-label="Online"
          />
        </Avatar>
      </div>
      <AvatarGroup>
        {['SV', 'NJ', 'AB'].map((initials) => (
          <Avatar key={initials}>
            <AvatarFallback>{initials}</AvatarFallback>
          </Avatar>
        ))}
        <AvatarGroupCount>+9</AvatarGroupCount>
      </AvatarGroup>
    </div>
  );
}
```

## Usage

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from '@workspace/active-ui/components/primitives/avatar';

<Avatar>
  <AvatarImage src={person.photoUrl} alt={person.name} />
  <AvatarFallback>{person.initials}</AvatarFallback>
</Avatar>;
```

## Anatomy

- `Avatar`: the circle. `size`: `sm`, `default` or `lg`.
- `AvatarImage`: the picture, shown once it has loaded.
- `AvatarFallback`: shown until then, or instead when there is no image or it fails.
- `AvatarBadge`: a small dot on the edge, for a status. Give it a colour with `className` and,
  when it carries meaning, `role="img"` with an `aria-label`.
- `AvatarGroup` and `AvatarGroupCount`: avatars that overlap, ending in a count of the rest.

## What your application provides

- The image URL and the `alt` text: the person's name, or `alt=""` when the name is written next
  to the avatar anyway.
- The initials or another fallback; the package does not derive initials from a name, because that
  depends on the language and the name.

## Accessibility

- An avatar with a visible name beside it is decoration: give the image `alt=""`.
- A status shown only as a coloured dot needs a text alternative (`aria-label` with `role="img"`).

## API

### Avatar

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "lg" \| "sm"` | no | The diameter: `sm`, `default` or `lg`. |
| `render` | `ComponentRenderFn<HTMLProps, AvatarRootState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

### Other parts

**AvatarImage**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | no | Whether the image element stays mounted and loads in place instead of being preloaded. Supports `loading="lazy"` and optimized image components such as `next/image`. |
| `onLoadingStatusChange` | `((status: ImageLoadingStatus) => void)` | no | Callback fired when the loading status changes. |
| `render` | `ComponentRenderFn<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, AvatarImageState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

**AvatarFallback**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `delay` | `number` | no | How long to wait before showing the fallback. Specified in milliseconds. |
| `render` | `ComponentRenderFn<HTMLProps, AvatarFallbackState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

**AvatarGroup**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |

AvatarGroup has no props of its own.

**AvatarGroupCount**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |

AvatarGroupCount has no props of its own.

**AvatarBadge**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |

AvatarBadge has no props of its own.

> [!NOTE]
> **Based on shadcn/ui**
>
> This page adapts the Avatar documentation of shadcn/ui (MIT licence) to this
> package; see [Third-party notices](/third-party-notices).