HyAvatar

Usage examples on this page are written for Lit / plain HTML (<hy-avatar>). The same component ships as HyAvatar in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A flexible avatar component for displaying user profile images or initials.

Key Features

• Display profile images or initials via explicit showInitials prop
• Multiple size options (small, medium, large) with responsive touch targets
• Showroom variant override (default, hover, active, focus); real disabled state via disabled prop
• Accessible with proper ARIA attributes and keyboard navigation
• Event-driven image loading feedback
• High contrast mode support
• Touch-friendly sizing on mobile devices (minimum 44px touch targets)
• Reduced motion support for accessibility

Accessibility

• Requires alt text for images or aria-label for initials
• Proper focus indicators for keyboard navigation
• High contrast mode support with enhanced borders
• Screen reader friendly with role="img"
• Minimum 44x44px touch targets on mobile devices

Display Control

The avatar uses the showInitials prop to explicitly control display:

• When showInitials={false} (default): Shows image if src is provided
• When showInitials={true}: Shows initials if provided (ignores src)
• No automatic fallback behavior - developers control what displays

CSS Custom Properties

The component integrates with the design system through CSS custom properties:

• --hy-avatar-background-identity-rest: Background color at rest
• --hy-avatar-background-identity-hover: Background color on hover
• --hy-avatar-background-identity-pressed: Background color when pressed
• --hy-avatar-background-identity-focus: Background color when focused
• --hy-avatar-background-neutral-disabled: Background color when disabled
• --hy-avatar-foreground-inverse-rest: Initials text color
• --hy-avatar-foreground-default-disabled: Initials text color when disabled
• --hy-avatar-radius-full: Border radius
• --hy-avatar-opacity-disabled: Opacity for disabled image
• --hy-avatar-size-sm, --hy-avatar-size-md, --hy-avatar-size-lg: Size dimensions

Categorical Coloring

When category-group is set the avatar paints itself with a color from the named palette in the active DS's roles.categorical map (--hy-background-{group}-{N}-*). identity is hashed via hashToCategorical against the group's --hy-{group}-count; slot-index is an explicit 1-indexed slot in the group and beats identity when both are set.

The component renders a categorical color only when all three preconditions hold: category-group is set, the DS defines that group, and the group has at least one ramp. Any failure → default (gray) styling, no console noise. Out-of-range slot-index (above the group's count, below 1, NaN) also falls back to gray.

Common Use Cases

Examples

Basic Avatar with Image

<hy-avatar src="/path/to/image.jpg" alt="John Doe" size="medium"> </hy-avatar>

Avatar with Initials

<hy-avatar initials="JD" show-initials aria-label="John Doe" size="medium"> </hy-avatar>

Toggle Between Image and Initials

<!-- Programmatically control which displays -->
<hy-avatar src="/path/to/image.jpg" alt="John Doe" initials="JD" show-initials size="large">
</hy-avatar>

Disabled Avatar

<hy-avatar src="/path/to/image.jpg" alt="Inactive User" disabled size="medium"> </hy-avatar>

Interactive Avatar with Event Handlers

<hy-avatar
  src="/path/to/image.jpg"
  alt="John Doe"
  size="medium"
  @activate="${handleClick}"
  @image-load="${handleLoad}"
  @image-error="${handleError}"
>
</hy-avatar>

Different Sizes

<hy-avatar src="/path/to/image.jpg" alt="User" size="small"></hy-avatar>
<hy-avatar src="/path/to/image.jpg" alt="User" size="medium"></hy-avatar>
<hy-avatar src="/path/to/image.jpg" alt="User" size="large"></hy-avatar>

API

Properties

Property	Attribute	Type	Default	Description
src	src	string | undefined	—	—
alt	alt	string	''	—
initials	initials	string | undefined	—	—
size	size	'small' | 'medium' | 'large'	'medium'	—
variant	variant	'default' | 'hover' | 'active' | 'focus'	'default'	—
emphasis	emphasis	'solid' | 'outlined'	'solid'	—
disabled	disabled	boolean	false	—
ariaLabel	aria-label	string | null	null	—
showInitials	show-initials	boolean	false	—
categoryGroup	category-group	string | undefined	—	—
identity	identity	string | undefined	—	—
slotIndex	slot-index	number | undefined	—	—

Events

Event	Detail	Description
activate	—	Fired when avatar is clicked (not when disabled)
image-load	—	Fired when image successfully loads
image-error	—	Fired when image fails to load

CSS Parts

Part	Description
base	The avatar's base wrapper element
image	The avatar's image element
initials	The avatar's initials text element

CSS Custom Properties

Property	Description
--hy-avatar-font-family	Font family override for the initials text (default: per-size caption family)
--hy-avatar-font-size	Font size override for the initials text (default: per-size caption size)
--hy-avatar-font-weight	Font weight override for the initials text (default: per-size caption weight)
--hy-avatar-letter-spacing	Letter spacing override for the initials text (default: per-size caption spacing)
--hy-avatar-hover-duration	Transition duration for hover and focus state feedback
--hy-avatar-hover-easing	Transition easing for hover and focus state feedback