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
| Slot | Required | Description |
|---|---|---|
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
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | - | Full name used for the accessible label and as source of derived initials and hash color. |
image | object | - | Image object with url and alt keys. When set, renders an <img> element. |
status | Enum: online, offline, away, busy | - | Status indicator value. |
hash | string | - | Hash string for deterministic background color. Defaults to name when omitted. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.rounded | Shape | - | Rounded corners. |
.square | Shape | - | Sharp corners. |
.circle | Shape | - | Perfect circle. |
.flat | Elevation | Yes | No elevation. |
.raised | Elevation | - | Slight elevation. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-avatar-hash | Consumer | - | 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-color | Script | - | 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
alttext or anaria-labelon 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-labelor 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 setdata-avatar-coloralso works with no JS. - With JS:
[data-avatar-hash]elements are scanned and assigned a deterministicdata-avatar-colorfrom the palette. - How to enable: ship Semetrika's JS bundle.
avatar.jsregisters 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 sharedMutationObserver; the script itself installs no listeners or observers of its own.