Avatar

Install

pnpm dlx shadcn@latest add @vegastack/avatar

Usage

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

<Avatar
  src="https://cdn.example.com/u/ada.webp"
  alt="Ada Lovelace"
  fallback="AL"
/>;

Presentational only. Avatar takes a fully-resolved, public src. It does not fetch data or resolve storage keys — resolving an R2 (or any CDN) key to a public URL stays app-side, so resolve it before passing src. The image only paints once it has loaded; until then (or on error) the fallback shows, so there is never a broken-image icon.

Anatomy

Avatar is a compound component. Every exported part, with the data-slot it renders (generated from the canonical source):

Examples

Anatomy

Avatar wraps Base UI Avatar.Root → Avatar.Image → Avatar.Fallback behind a single flat prop API. AvatarGroup is a layout shell that overlaps its Avatar children.

<AvatarGroup>
  <Avatar src={url} alt="…" fallback="AL" /> {/* Root → Image → Fallback */}
  <Avatar fallback="+5" /> {/* overflow indicator (no src → fallback) */}
</AvatarGroup>

Sizes

xs, sm, default, lg, and xl — the diameter and the fallback text scale together.

Fallback

When src is absent or the image fails to load, the fallback shows — typically 1–2 uppercase initials, or an icon. Without a fallback, the bare bg-accent circle remains.

Both the no-src path and the image-error path resolve to the same fallback, so a broken or unreachable src never leaves a broken-image icon — it falls back to the initials (or icon):

Fallback delay

fallbackDelay (ms) waits before swapping in the fallback, avoiding a flash of initials for fast-loading images — the bare bg-accent circle holds the space until either the image paints or the delay elapses. It is forwarded to Base UI Avatar.Fallback.

<Avatar src={url} alt="Ada Lovelace" fallback="AL" fallbackDelay={600} />

Group

AvatarGroup overlaps its children into a stack and gives each a ring-background so the overlap reads cleanly on any surface. Add a trailing Avatar with a +N fallback to indicate overflow. Control overlap density with spacing (tight · default · loose).

The three spacing values side by side — tight tucks each avatar furthest under the previous, loose overlaps the least:

Playground

Adjust the avatar size and the group's overlap spacing, then copy the generated JSX.

<AvatarGroup>
  <Avatar fallback="AL" />
  <Avatar fallback="GH" />
  <Avatar fallback="+3" />
</AvatarGroup>

API Reference

Avatar

AvatarGroup

Accessibility

• When src is provided, alt is required. Pass the person's or entity's name for meaningful avatars; pass alt="" only when adjacent text or the wrapping control already names the entity.
• When src is absent, no <img> is rendered; the fallback/root carries the visible identity.
• The fallback (initials or icon) is the visible label when no image loads; keep it meaningful (initials of the same name) so the avatar stays identifiable without the picture.
• Avatar is non-interactive by default. When an avatar links to a profile, wrap it in an interactive element (a Button/link) that owns the accessible name and focus ring — don't rely on the image alone.

Do / Don't