# Avatar

Represent a person with an image or a text fallback.

Profile photo with initials fallback

[Complete TSX file](/examples/avatar/default.tsx)

```tsx
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@/siteplane/components/avatar";

export default function Example() {
  return (
    <Avatar>
      <AvatarImage
        alt="Mara Ellis"
        src="https://ui.siteplane.io/avatars/mara.webp"
      />
      <AvatarFallback>ME</AvatarFallback>
    </Avatar>
  );
}
```

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/avatar
```

With npm: `npx shadcn@4.18.0 add @siteplane/avatar`. [Registry JSON](/registry/avatar.json) lists source files and dependencies.

For this page’s examples, also install:

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/avatar-group
```

## Usage

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

<Avatar>
  <AvatarImage src="/avatars/mara-ellis.png" alt="Mara Ellis" />
  <AvatarFallback>ME</AvatarFallback>
</Avatar>;
```

## Composition

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

AvatarFallback shows while the image loads, when it fails, or when no image is set.

## Icon placeholder

When there is no image and no name to abbreviate, place an icon in AvatarFallback. Name the avatar for its context.

Guest avatar with user icon

[Complete TSX file](/examples/avatar/fallback.tsx)

```tsx
"use client";

import { UserIcon } from "lucide-react";
import { Avatar, AvatarFallback } from "@/siteplane/components/avatar";

export default function Example() {
  return (
    <Avatar aria-label="Guest" role="img">
      <AvatarFallback>
        <UserIcon aria-hidden="true" className="size-4" />
      </AvatarFallback>
    </Avatar>
  );
}
```

## Size and shape

Use explicit classes to customize dimensions. There is no size or shape prop. A radius class on Avatar applies to its image and its fallback, and the initials grow with the avatar.

Avatar sizes and shapes

[Complete TSX file](/examples/avatar/sizes.tsx)

```tsx
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@/siteplane/components/avatar";

export default function Example() {
  return (
    <div className="flex items-center gap-4">
      <Avatar>
        <AvatarImage
          alt="Mara Ellis"
          src="https://ui.siteplane.io/avatars/mara.webp"
        />
        <AvatarFallback>ME</AvatarFallback>
      </Avatar>
      <Avatar className="size-12">
        <AvatarImage
          alt="Mara Ellis"
          src="https://ui.siteplane.io/avatars/mara.webp"
        />
        <AvatarFallback>ME</AvatarFallback>
      </Avatar>
      <Avatar className="size-16 rounded-md">
        <AvatarImage
          alt="Mara Ellis"
          src="https://ui.siteplane.io/avatars/mara.webp"
        />
        <AvatarFallback>ME</AvatarFallback>
      </Avatar>
    </div>
  );
}
```

## Avatar group

Overlap avatars with [Avatar Group](/docs/components/avatar-group/). It draws a ring in the surface color around each avatar and around the `AvatarGroupCount` of the remaining members; the application supplies the member data.

Project members with overflow count

[Complete TSX file](/examples/avatar/group.tsx)

```tsx
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@/siteplane/components/avatar";
import {
  AvatarGroup,
  AvatarGroupCount,
} from "@/siteplane/components/avatar-group";

const members = [
  {
    name: "Mara Ellis",
    initials: "ME",
    image: "https://ui.siteplane.io/avatars/mara.webp",
  },
  {
    name: "Ben Carter",
    initials: "BC",
    image: "https://ui.siteplane.io/avatars/ben.webp",
  },
  {
    name: "Sofia Nguyen",
    initials: "SN",
    image: "https://ui.siteplane.io/avatars/sofia.webp",
  },
];

export default function Example() {
  return (
    <AvatarGroup>
      {members.map((member) => (
        <Avatar key={member.name}>
          <AvatarImage alt={member.name} src={member.image} />
          <AvatarFallback>{member.initials}</AvatarFallback>
        </Avatar>
      ))}
      <AvatarGroupCount>
        +2<span className="sr-only"> more members</span>
      </AvatarGroupCount>
    </AvatarGroup>
  );
}
```

## Status indicator

Pass `status` to show a presence dot at the bottom-end corner. The dot is named for assistive technology (Online, Away, Busy or Offline), because color alone does not convey it. Its ring takes the color of the surface the avatar sits on.

Avatars with presence status

[Complete TSX file](/examples/avatar/status.tsx)

```tsx
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@/siteplane/components/avatar";

const people = [
  {
    name: "Mara Ellis",
    initials: "ME",
    image: "https://ui.siteplane.io/avatars/mara.webp",
    status: "online",
  },
  {
    name: "Ben Carter",
    initials: "BC",
    image: "https://ui.siteplane.io/avatars/ben.webp",
    status: "offline",
  },
] as const;

export default function Example() {
  return (
    <div className="flex items-center gap-4">
      {people.map((person) => (
        <Avatar key={person.name} status={person.status}>
          <AvatarImage alt={person.name} src={person.image} />
          <AvatarFallback>{person.initials}</AvatarFallback>
        </Avatar>
      ))}
    </div>
  );
}
```

## API reference

### Avatar

The root renders a 32 px circular span with 12 px text; a size class such as `size-10` replaces the size. It accepts [Base UI Avatar Root props](https://base-ui.com/react/components/avatar#root), including `render`, `children`, and string `className`.

`status` (`"online"`, `"away"`, `"busy"` or `"offline"`) adds a presence dot at the bottom-end corner; the avatar then sits in a wrapper that carries the dot, so the circle's clipping does not cut it. `statusLabel` replaces the dot's accessible name, which defaults to the English status name. The dot's ring takes the color of the surface the avatar sits on (Card, Dialog, Popover and the other kit surfaces); on a surface of your own, set `--avatar-status-ring` to that color.

### AvatarImage

Accepts Base UI Avatar Image props. `src` supplies the image URL, `alt` its accessible text, and `onLoadingStatusChange` reports image loading status. The image fills its root with `object-cover`; no image is supplied by default.

### AvatarFallback

Accepts Base UI Avatar Fallback props. `children` supplies initials or another replacement. `delay` optionally postpones the fallback according to the foundation contract. The kit adds no delay override and renders a full-size muted circle.

`AvatarPrimitive` exports the underlying Base UI namespace. The three styled parts add no other owned props. Styled parts accept string classes; they do not evaluate foundation `className` callbacks.

[Read the installed source](/source/avatar).

## Usage notes

Give every avatar a name. An image needs a meaningful `alt`; an avatar that shows only initials or an icon can take `role="img"` and an `aria-label` on Avatar, as in the icon placeholder example. Avoid repeating a person’s name if adjacent text already provides it. Avatars do not manage presence, navigation, upload, or group overflow; those are application responsibilities.