Avatar

InstallCopy Anchor Link

pnpm exec vegastack-design verify avatar

pnpm dlx shadcn@4.21.0 add @vegastack/avatar

UsageCopy Anchor Link

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

<Avatar>
  <AvatarImage src="/team/ada.png" alt="Ada Lovelace" />
  <AvatarFallback>AL</AvatarFallback>
</Avatar>;

AnatomyCopy Anchor Link

ExamplesCopy Anchor Link

CompositionCopy Anchor Link

Avatar wraps an AvatarImage, an AvatarFallback and an optional AvatarBadge. AvatarGroup wraps a run of Avatars and an optional trailing AvatarGroupCount.

BasicCopy Anchor Link

A basic avatar with an image and a fallback.

BadgeCopy Anchor Link

Use AvatarBadge to add a badge to the avatar. It is positioned at the bottom end corner and sized from the avatar's own size. Pass a className for a custom fill — here the success token.

Badge with IconCopy Anchor Link

An icon can go inside AvatarBadge. At size="sm" the icon is hidden, because the badge is too small to carry one.

Avatar GroupCopy Anchor Link

Use AvatarGroup to overlap a run of avatars. Each child picks up a background-colored ring so the stack reads as separate faces.

Avatar Group CountCopy Anchor Link

Use AvatarGroupCount to close the stack with a count. It tracks the group's avatar size.

Avatar Group with IconCopy Anchor Link

AvatarGroupCount also takes an icon — an "add a teammate" affordance at the end of the stack. Give it an accessible name, since an icon alone has no text.

SizesCopy Anchor Link

Use the size prop to change the avatar diameter: sm is 24px, default is 32px and lg is 40px. Fallback initials use text-xs at every size so they remain visually secondary to the person or entity the avatar represents.

DropdownCopy Anchor Link

An avatar is a common dropdown trigger. Render the trigger as a Button and put the Avatar inside it, so the control — not the image — owns the focus and the accessible name.

RTLCopy Anchor Link

The badge is placed with end-0, so a right-to-left document moves it to the bottom left and mirrors the group's overlap without any extra work.

HuesCopy Anchor Link

AvatarFallback takes a hue — one of the ten tag hues (AvatarHue) — and paints the initials in that hue's ink on its subtle fill: a person's own colour, so people are told apart before any photo exists. Without a hue the fallback stays muted. For a person, compose PersonAvatar, which reads the hue, the photo and the initials from one Person.

API ReferenceCopy Anchor Link

AccessibilityCopy Anchor Link

• AvatarImage renders a native <img>. Give it an alt naming the person; use alt="" when the avatar sits beside their name and would only repeat it.
• AvatarFallback paints when the image has not loaded or has failed. Initials are text, so they are read out; an icon fallback is decorative and needs a name on whatever wraps it.
• AvatarBadge is a decorative dot. A status it encodes — online, verified — must also exist as text somewhere a screen reader can reach.
• An avatar is not a control. When it acts as one, wrap it in a Button and name the button.

Do / Don'tCopy Anchor Link

DeviationsCopy Anchor Link

Upstream's file plus packages/ui/upstream/patches/avatar.patch. Every hunk:

• DOC-2 — cn is imported from @vegastack/design, and the file carries the registry provenance header.
• TYP-14 — AvatarFallback uses text-xs at all three sizes while preserving upstream's public size API and diameters. The decision and approval provenance are recorded in docs/plans/2026-09-18-regent-avatar-148.md.
• API-32 — AvatarFallback takes an optional hue (the ten --tag-* hues, exported as AvatarHue) painting bg-tag-{hue}-subtle text-tag-{hue}-text and writing data-hue; with no hue it keeps upstream's muted fallback.