Avatar

Shows a person or entity as a photo, generated initials, or name-derived palette background.

Set config.name for accessible labeling and auto-initials, or override with config.initials or config.src. Tune config.size and config.shape to match surrounding typography. Compose with PresenceBadge or CounterBadge for status overlays, and AvatarGroup for stacked participant lists.

  • User lists, comment threads, and profile headers
  • Entity representation when a photo is unavailable
  • Compact identity markers beside names in tables and navigation
  • Set config.name for accessible labels and auto-generated initials.
  • Set config.src when a profile photo is available.
  • Override with config.initials for custom letter pairs.
  • Tune config.size and config.shape to match surrounding typography.
  • Named avatars default to a name-derived palette via AvatarConfig::name(); use AvatarColor::Neutral explicitly when needed.
Name-derived initials

Name-derived initials appear when no image is provided — the common pattern in lists and comments.

JD
Profile image

Photo avatars display the image with initials as fallback on load error.

JD
Custom initials

Explicit initials override auto-generation from the display name.

AB
Size matrix

Pixel size tokens align avatars with surrounding typography and layout grids.

A
C
E
Shape variants

Circular and square shapes suit profile lists and compact entity chips.

A
C
Theme background token

Initials fallback uses the neutral avatar surface token with a visible stroke.

TU
Name-derived palette

Display names map to stable palette colors when color is Colorful.

AA
BB
Named color presets

Explicit palette colors for initials and icon fallback.

C
T
P
Brand color

Brand-tinted initials for product-owned identity surfaces.

B
With presence badge

Availability dot anchored to an avatar — common in contact lists.

JD
With counter badge

Numeric overlay for unread counts on avatar hosts.

JD7
Avatar group

Stacked avatars with overflow chip.

AABBCC+2