Avatar

Avatar represents a person, team, or account with an image and a reliable text fallback.

Purpose

Avatar represents a person, team, or account with an image and a reliable text fallback.

Image and fallback

MCLU

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

export function Example() {
  return (
    <Avatar>
      <AvatarImage src="/examples/avatar-maya.svg" alt="Maya Chen" />
      <AvatarFallback>MC</AvatarFallback>
    </Avatar>
  );
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/avatar

Import

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

Need the machine-readable source metadata? View registry JSON.

Usage

Avatar represents a person or workspace. Always provide a fallback for missing images.

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

export function Example() {
  return (
    <Avatar>
      <AvatarImage src="/examples/avatar-maya.svg" alt="Maya Chen" />
      <AvatarFallback>MC</AvatarFallback>
    </Avatar>
  );
}

Examples

Sizes, radius, grouping and user rows are className compositions of the same three slots.

Sizes

Avatar has no size prop. Scale the root with className; image and fallback fill it.

AVAVAV

<Avatar>
  <AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="size-12 text-sm">
  <AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="size-16 text-base">
  <AvatarFallback>AV</AvatarFallback>
</Avatar>

Radius

Radius is a className on the root and the fallback, not a prop.

MCMCMC

<Avatar className="rounded-md">
  <AvatarImage alt="Maya Chen" src="/examples/avatar-maya.svg" />
  <AvatarFallback className="rounded-md">MC</AvatarFallback>
</Avatar>
<Avatar className="rounded-xl">
  <AvatarImage alt="Maya Chen" src="/examples/avatar-maya.svg" />
  <AvatarFallback className="rounded-xl">MC</AvatarFallback>
</Avatar>
<Avatar className="rounded-full">
  <AvatarImage alt="Maya Chen" src="/examples/avatar-maya.svg" />
  <AvatarFallback>MC</AvatarFallback>
</Avatar>

Avatar group

JDMRAK+2

<div className="flex -space-x-2">
  {groupMembers.map((member) => (
    <Avatar className="ring-2 ring-background" key={member.fallback}>
      <AvatarFallback aria-label={member.label}>
        {member.fallback}
      </AvatarFallback>
    </Avatar>
  ))}
  <span className="inline-flex size-8 items-center justify-center rounded-full border bg-muted font-medium text-muted-foreground text-xs ring-2 ring-background">
    +2
  </span>
</div>

With user info

Jamie Doe

Product team

<div className="flex min-w-0 items-center gap-3">
  <Avatar className="size-10 text-sm">
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <div className="grid min-w-0 gap-0.5">
    <p className="truncate font-medium text-sm">Jamie Doe</p>
    <p className="truncate text-muted-foreground text-xs">Product team</p>
  </div>
</div>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

AvatarImage renders the image and AvatarFallback renders initials or another short fallback.
The root defaults to a 32px circular avatar. Change size or radius with existing system classes on Avatar; do not create a parallel size API.
Keep data-slot="avatar", avatar-image, and avatar-fallback intact.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

Avatar has no local animation. Image and fallback switching remains native to Base UI.
Avatar groups are static layout compositions and must not add ad-hoc scale or hover motion.

Accessibility

Give AvatarImage meaningful alt text when the image conveys information. Use empty alt text when a nearby label already names the person.
Keep fallback text short and understandable.
Provide text outside a visual avatar group that names or summarizes its members.
Never communicate identity, role, or status through the image alone.

Implementation Guidance

Use Avatar only for people, teams, or account identity.
Do not create wrapper primitives or local size and radius APIs.
Preserve the image, fallback, and slot contract.