Components

Avatar

A circular avatar built on Base UI's Avatar. Renders src when it loads and falls back to initials derived from name otherwise. AvatarGroup overlaps a row of avatars from flat data.

Install

npx shadcn@latest add @alix/avatar

Preview

JPRSMK

JPRSMKAL

Usage

<DefaultAvatar src={user.photo} alt={user.name} name={user.name} />
<DefaultAvatar size="lg" name="Maya Khan" />

<AvatarGroup
  avatars={[
    { name: "Jordan Park" },
    { name: "Rafael Silva" },
    { name: "Maya Khan" },
    { name: "Alex Lam" },
  ]}
/>

Examples

Portrait with initials fallback

Pair every portrait with alt text and a name so people rows still scan when an image is absent — the first and last initials stand in.

AWDCMI

<DefaultAvatar src="/brand/portrait-1.jpg" alt="Amelia Ward" name="Amelia Ward" />
<DefaultAvatar src="/brand/portrait-2.jpg" alt="Daniel Cho" name="Daniel Cho" />
<DefaultAvatar name="Maya Iqbal" />

Contributor group

AvatarGroup overlaps a row from flat avatar data when shared ownership matters more than any single portrait.

AWDCMIRS

<AvatarGroup
  avatars={[
    { name: "Amelia Ward" },
    { name: "Daniel Cho" },
    { name: "Maya Iqbal" },
    { name: "Rafael Silva" },
  ]}
/>

Owner card

Avatar, Badge, Button, and Panel make a compact ownership summary for an engagement workspace.

Engagement owner

Turnaround plan

Available

Amelia Ward

Managing director, London

<Panel
  title="Engagement owner"
  description="Turnaround plan"
  actions={<Badge variant="success" dot>Available</Badge>}
>
  <div className="flex flex-wrap items-center justify-between gap-4">
    <div className="flex min-w-0 items-center gap-3">
      <DefaultAvatar
        size="lg"
        src="/brand/portrait-1.jpg"
        alt="Amelia Ward"
        name="Amelia Ward"
      />
      <div className="min-w-0">
        <p className="truncate text-sm font-medium text-foreground">Amelia Ward</p>
        <p className="truncate text-xs text-muted-foreground">
          Managing director, London
        </p>
      </div>
    </div>
    <Button size="sm" variant="outline">View profile</Button>
  </div>
</Panel>

When to use it

Use it for

People rows, owner cards, and workspace headers where a named person needs a stable visual handle.
Small contributor groups where overlap communicates shared ownership without taking a full row.
Initials fallbacks derived from the person's name when a portrait is missing or fails to load.

Reach for something else

Full people directory cards with job title, location, and contact links — use EmployeeCard instead.
Status labels or phase chips — use Badge instead.
Dense tabular ownership lists — use DataTable instead.

Props

Prop	Type	Default	Description
src / alt	string	—	Image source and its alt text. Shown once loaded.
name	string	—	Full name — the first and last initials are the fallback while the image loads, fails, or is absent.
size	"sm" \| "default" \| "lg"	"default"	Tile size + text scale.
avatars (AvatarGroup)	DefaultAvatarProps[]	—	Flat avatar data rendered as an overlapping row — one DefaultAvatar per record.