GET STARTED

Import

Import only the identity primitives you render from the granular entry point.

import {
  NeuralAvatar,
  NeuralAvatarGroup,
} from '@neural-ng/core/avatar';

@Component({ imports: [NeuralAvatar, NeuralAvatarGroup] })

Deterministic fallback priority

A valid image wins, followed by explicit or name-derived initials, an icon class, then projected content. A failed image never remains broken.

GHMHAI

Sizes, shapes and image fit

Five size presets combine with circle, rounded or square geometry. Image fit remains independently configurable as cover or contain.

Responsive native image pipeline

srcSet, sizes, loading, decoding, fetch priority and referrer policy map directly to the native image. The root exposes data-image-state as loading, loaded, error or fallback.

Image error and retry

The native error event remains observable while the visual switches to fallback. Changing src resets failure state and retries the new image.

Waiting for the native image error event.

Status and notification Badges

Avatar owns identity; the reusable Badge directive owns dots, counts, severity, logical placement and announcement. No Avatar-only badge API is duplicated.

AvatarGroup and localized overflow

max keeps useful identities visible and replaces the remainder with an accessible +N. The source projection is preserved and reacts when children or max change.

GHMH +3

Unstyled and typed class slots

Headless mode retains fixed identity structure, error fallback, semantics, group visibility and logical direction while consumer classes own every visual surface.

Beta boundaries

Image alternatives

alt is passed to the native image. When omitted, name becomes the alternative. Set alt="" explicitly only when surrounding visible text already names the person and the image is decorative.

Fallback semantics

Initials, icon and projected fallback visuals are hidden from assistive technology; the root uses role="img" with the resolved ariaLabel, name or alt. Without any name, the fallback stays decorative.

Group naming and overflow

Providing ariaLabel creates a named role="group". The overflow count substitutes every {count} occurrence in the localized label; keep that placeholder in translations.

Badge announcements

A visual status dot needs neuralBadgeAriaLabel. Counts should announce their meaning, not only the number. Avatar itself never duplicates these semantics.

RTL and logical layout

Group overlap and Badge positions use inline start/end, so document direction changes require no alternate markup. Avatar has no keyboard behavior because identity alone is not interactive.

NeuralAvatar inputs

NeuralAvatar outputs

NeuralAvatarGroup inputs

Typed class slots

Avatar

AvatarGroup

Avatar

AvatarGroup