@kit-ng-ui/avatar

Image / text / icon avatars and a stacked group, for Kit UI. Mirrors ant-design's Avatar and Avatar.Group.

Install

pnpm add @kit-ng-ui/avatar @kit-ng-ui/core @kit-ng-ui/icons

Styles

// app styles.scss
@use '@kit-ng-ui/core/styles' as *;
@use '@kit-ng-ui/avatar/styles' as avatar;

Use

import { Component } from '@angular/core';
import { KitAvatarComponent, KitAvatarGroupComponent } from '@kit-ng-ui/avatar';

@Component({
  standalone: true,
  imports: [KitAvatarComponent, KitAvatarGroupComponent],
  template: `
    <kit-avatar>U</kit-avatar>
    <kit-avatar src="/u/me.png" alt="me" />
    <kit-avatar icon="github" shape="square" />
    <kit-avatar size="lg">Long Name</kit-avatar>

    <kit-avatar-group [maxCount]="3" size="large">
      <kit-avatar src="/1.png" />
      <kit-avatar src="/2.png" />
      <kit-avatar>K</kit-avatar>
      <kit-avatar>R</kit-avatar>
    </kit-avatar-group>
  `,
})
export class Demo {}

API

<kit-avatar>

| Input | Type | Default | Description | | ------------ | --------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------ | | src | string \| null | null | Image URL. Falls back to text/icon on error. | | srcSet | string \| null | null | Native srcset for the underlying <img>. | | alt | string \| null | null | Native alt for accessibility. | | icon | string \| null | null | Icon name from the registry. Shown when src is absent or failed. | | shape | 'circle' \| 'square' | 'circle' | Corner radius. | | size | 'sm' \| 'md' \| 'lg' \| number \| string | 'md' | Preset, pixel number, or any CSS length. | | loading | 'eager' \| 'lazy' | 'eager' | Native loading attribute for the <img>. | | gap | number | 4 | Horizontal padding (px) when auto-fitting projected text. |

| Output | Payload | Description | | ------------ | --------- | ----------------------------------------------------------------- | | imageError | Event | Fires when the image fails to load. The component falls back automatically. |

Projected content (<ng-content>) renders as text only when no src and no icon are set. Text is auto-scaled to fit when the avatar size is a known pixel value; if size is a CSS string like "3rem" the text is NOT scaled (the component cannot measure container width statically).

<kit-avatar-group>

Stacks projected <kit-avatar> children with overlap.

| Input | Type | Default | Description | | ---------- | --------------------------------------------------- | ------- | ---------------------------------------------------------- | | maxCount | number \| null | null | Maximum number of avatars to render. Extras collapse into a "+N" chip. | | size | KitAvatarSize \| null | null | Reserved for future propagation; v0.1 does not push to children — see TODO below. | | shape | 'circle' \| 'square' \| null | null | Reserved for future propagation; v0.1 does not push to children — see TODO below. |

Behavior notes

• Image error is non-recoverable per render — once the image errors, the component locks to the fallback path. Swapping [src] to a different URL resets the error state.
• The group hides overflowing children via display: none set on each host element. This preserves their identity for change-detection without re-projecting.
• v0.1 does NOT propagate [size] / [shape] from group to children. Set them on each <kit-avatar> directly. Cascade behavior will be added when the @kit-ng-ui/config-provider lands.

TODO (parity)

• maxPopoverPlacement — overlay-based popover listing the overflowing avatars. Pending the @kit-ng-ui/popover overlay primitive.
• Propagation of size / shape from group to children (waiting on a host-context contract via @kit-ng-ui/config-provider).
• Per-overflow-chip color overrides — deferred until a real use case lands; for now, restyle the chip via CSS targeting .kit-avatar--overflow.