Avatar

Image with an initials fallback that keeps layout stable while it loads. The image is only mounted once it is ready, so there is no flash or shift.

Preview

Live preview

AKJDMP

Usage

Examples

In a list row

AKAda K.

<div className="flex items-center gap-3">
  <Avatar size="sm">
    <AvatarImage src={user.avatarUrl} alt="" />
    <AvatarFallback>{initials(user.name)}</AvatarFallback>
  </Avatar>
  <span>{user.name}</span>
</div>

Grouped avatars with overflow

AKJDMP+2

<AvatarGroup max={3}>
  {team.map((member) => (
    <Avatar key={member.id}>
      <AvatarImage src={member.avatarUrl} alt="" />
      <AvatarFallback>{initials(member.name)}</AvatarFallback>
    </Avatar>
  ))}
</AvatarGroup>

Reference

Props

Prop	Type	Default	Description
size	"sm" \| "md" \| "lg"	"md"	Diameter of the avatar (8, 10 and 12 = 32/40/48px).
variant	"default" \| "brand" \| "surface"	"default"	Background used before an image loads and behind initials.
AvatarImage src / alt	string	—	Rendered only after the image loads; alt becomes the accessible name.
AvatarFallback	ReactNode	—	Initials or icon shown while (or when) no image is available.
AvatarGroup max	number	4	Avatars rendered before the "+N" overflow counter appears.
AvatarGroup spacing	number	-10	Overlap in pixels between avatars (negative values overlap).
className	string	—	Merged last, so you can override size or rounding.

Accessibility

Pass alt on AvatarImage so the image carries its own name; use alt="" when adjacent text already names the person.
The fallback renders text (initials), so the avatar is never an empty box for screen readers.
The root is presentational — it has no implicit role, so it will not be announced as a widget.
AvatarGroup's overflow counter is role="img" labelled "N more", so hidden members are counted for screen readers.
Avatars inside a group are decorative when the list already names each person — keep their alt empty in that case.
Sizes are fixed, so swapping image for initials causes no layout shift.

Live preview

Examples

In a list row

Grouped avatars with overflow

Props

Accessibility notes