Avatar

"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

pnpm dlx shadcn@4.18.0 add @siteplane/avatar

Complete the one-time setup first. Registry JSON lists source files and dependencies.

For this page’s examples, also install:

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

Usage

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

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

Composition

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.

"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.

MEMEME

"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. 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.

MEBCSN+2

"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>
  );
}

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.

MEBC

"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

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, 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.

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.