Skip to main content

Avatar

User or content profile representation with image, initials, or icon fallback. Supports size variants, shape values, an optional status indicator via data attribute, and hash-based background color for initials so users get a stable, deterministic color without editors choosing one manually.

Usage​

When to use

  • Representing a person in directories, team pages, comments, or author bylines
  • User menu or profile chips in product surfaces
  • Listing participants in a conversation or activity feed

When not to use

  • For standalone photography or editorial imagery - use the image component
  • For organization logos - use the logo component
  • For decorative circular images without identity meaning

Do

  • Provide a meaningful name via alt text or aria-label
  • Use initials when a photo is not available
  • Let the hash-based color do the work for initials - it stays stable per user

Don't

  • Rely on color alone to convey status - always pair with text
  • Use status indicators for editorial content; they are a product pattern
  • Nest avatars inside interactive avatars - keep click targets flat

API​

Slots​

SlotRequiredDescription
initials-One or two character initials fallback. Derived from name when omitted.
icon-Pre-rendered icon for fallback when no image or initials are available.

Props​

PropTypeDefaultDescription
namestring-Full name used for the accessible label and as source of derived initials and hash color.
imageobject-Image object with url and alt keys. When set, renders an <img> element.
statusEnum: online, offline, away, busy-Status indicator value.
hashstring-Hash string for deterministic background color. Defaults to name when omitted.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.roundedShape-Rounded corners.
.squareShape-Sharp corners.
.circleShape-Perfect circle.
.flatElevationYesNo elevation.
.raisedElevation-Slight elevation.

Attributes​

AttributeSet byRequiredDescription
data-avatar-hashConsumer-Consumer-supplied hash override. The JS reads this when generating a deterministic color swatch for the initials avatar; falls back to the name prop when absent.
data-avatar-colorScript-Computed color index (0-N) set by the JS after hashing. Drives the CSS background-color selector.

Examples​

Image​

Avatar displaying a user photo with alt text.

Initials​

Initials fallback with hash-based background color.

Icon fallback​

Icon fallback for unknown or deleted users.

Sizes​

Size values .sm, .md, and .lg side by side.

Square​

Rounded-square shape value.

Status​

Avatars with each status type: online, offline, away, busy.

Hash palette​

Grid of initials avatars showing the full hash-based color palette.

Name only​

Only a name is supplied, so the initials and the background color are both derived from it.

Accessibility​

  • WCAG 2.2 AA
  • Image avatars must have meaningful alt text or an aria-label on the root when alt is empty.
  • Initials avatars must announce the full person name, not just the letters.
  • Icon fallback avatars must communicate the role (e.g. "Unknown user", "Deleted account").
  • Status indicator is decorative; the status must also be communicated via text (in aria-label or a visually hidden span).
  • Status color is paired with text - color alone is never used (WCAG 1.4.1).
  • Size variants must not change the semantic meaning announced to assistive tech.

Dependencies​

  • icon - provides the fallback icon sprite

Progressive enhancement​

  • No JS: image, initials, and icon avatars render. Status indicator works purely from data-status. Manually set data-avatar-color also works with no JS.
  • With JS: [data-avatar-hash] elements are scanned and assigned a deterministic data-avatar-color from the palette.
  • How to enable: ship Semetrika's JS bundle. avatar.js registers with the bundle's boot orchestrator, which runs its init on DOM ready and re-runs it for dynamically added content via the orchestrator's shared MutationObserver; the script itself installs no listeners or observers of its own.
  • icon - fallback icon sprite
  • image - standalone photos without avatar treatment
  • tooltip - can wrap an avatar for name-on-hover