HyAvatar

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-accent-rest: Background color at rest
• --hy-avatar-background-accent-hover: Background color on hover
• --hy-avatar-background-accent-pressed: Background color when pressed
• --hy-avatar-background-accent-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>

Events

• activate - Fired when avatar is clicked (not when disabled)
• image-load - Fired when image successfully loads
• image-error - Fired when image fails to load