Avatar

A person's picture, with initials while it loads or if it fails. Includes a status badge and overlapping groups.

When to use

Use when: Showing who a person or account is, in lists, comments, or headers.
Avoid when: Representing things that aren't people or accounts; use an icon.

Installation

bunx shelf add avatar

The source lands in src/components/ui/avatar.tsx, along with any Shelf items it builds on, and .shelf/lock.json records what was installed. It's yours to edit.

Usage

import * as Avatar from "@/components/ui/avatar";

<Avatar.Root>
  <Avatar.Image src={user.photo} alt={user.name} />
  <Avatar.Fallback>AL</Avatar.Fallback>
</Avatar.Root>

Examples

Sizes

ALALAL

Badge

A status dot in the corner, such as online presence.

Group

Overlapping avatars, with a count for the rest.

MRJKSO

Built on

Packages: @base-ui/react, @stylexjs/stylex
Shelf items: foundations, utils
Accessibility: Focus, keyboard, and ARIA behavior come from Base UI.
Figma: In progress. See Designers and Figma.