Component v1.1.0 Foundations

Avatar

User or entity avatar with image, initials fallback, sizes, and shapes.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-avatar
Package
@ngnova/ui/avatar

Import

Standalone Tailwind v4
import { UiAvatarComponent } from '@ngnova/ui/avatar';

Usage & variants

Live examples use the public ui-avatar API, paired with the exact snippet a product team would paste into an Angular app.

API Reference

Contributor identity

User or entity avatar with image, initials fallback, sizes, and shapes.

Production guidance

Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.

When to use

Use beside user names, authors, table rows, comments, team lists, and account menus.

Watch for

Provide ariaLabel, alt, or label unless the avatar is intentionally decorative.

Product recipes

Apply Avatar in distinct, copyable product scenarios—not just an isolated component state.

Initials fallback

Initials are derived from the label.

Angular template ui-avatar-recipe.example.html
1
2
<ui-avatar label="Grace Hopper" />
<ui-avatar label="NgNova UI" shape="square" size="lg" />

Review team

Label a compact group of contributors while retaining a useful fallback for each person.

Angular template ui-avatar-recipe.example.html
1
2
3
4
5
<div class="flex -space-x-2" aria-label="Release reviewers">
  <ui-avatar label="Avery Chen" src="/people/avery.jpg" />
  <ui-avatar label="Morgan Lee" />
  <ui-avatar label="Sam Rivera" />
</div>

API Reference

Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.

Inputs

src ''
string

Optional image source.

alt ''
string

Image alternative text and accessible-label fallback.

label ''
string

Accessible label and initials source.

ariaLabel ''
string

Accessible label override for avatar images or generated initials.

size 'md'
'sm' | 'md' | 'lg'

Avatar dimensions.

shape 'circle'
'circle' | 'square'

Avatar border radius.

Accessibility

  • A loaded source renders one native image named by ariaLabel, alt, or label in that priority order.
  • Initials fallback uses role="img" with the same accessible-name priority; an entirely unnamed fallback is decorative.

Keyboard behavior

  • Avatar is visual and non-interactive; wrap it in a button or link only when it opens an action.

Testing guidance

  • Assert initials, accessible naming, image alt text, and error fallback.
  • No component harness is included because Avatar is non-interactive and its public image/fallback DOM is directly observable.