Avatar
User or entity identity with image, initials, icon fallback, presence status, and grouped stacks.
Import the public components from the published package entrypoint.
import { KuiAvatarComponent, KuiAvatarGroupComponent } from '@kikita-labs/ui';kui-avatar renders an image first, falls back to initials derived from name, then falls back to an icon when no initials are available.
<div class="basic-avatar-example">
<kui-avatar src="https://i.pravatar.cc/64?img=12" name="Nikita Repin" status="online" />
<kui-avatar name="Anya Murashova" />
<kui-avatar />
</div>size uses the shared Kikita size scale from xs to 2xl. shape defaults to circle for people; use square for bots, teams, channels, and other entities.
<div class="avatar-sizes-shapes-example">
<div class="avatar-sizes-shapes-example__row">
<kui-avatar name="Nikita Repin" size="xs" />
<kui-avatar name="Nikita Repin" size="sm" />
<kui-avatar name="Nikita Repin" size="md" />
<kui-avatar name="Nikita Repin" size="lg" />
<kui-avatar name="Nikita Repin" size="xl" />
<kui-avatar name="Nikita Repin" size="2xl" />
</div>
<div class="avatar-sizes-shapes-example__row">
<kui-avatar name="Design Bot" shape="square" />
<kui-avatar name="Release Team" shape="square" size="lg" />
</div>
</div>status renders a decorative presence dot and appends the presence text to the avatar accessible label.
<div class="avatar-status-example">
<kui-avatar name="Nikita Repin" status="online" />
<kui-avatar name="Anya Murashova" status="away" />
<kui-avatar name="Timur Ognev" status="busy" />
<kui-avatar name="Vera Saltykova" status="offline" />
</div>kui-avatar-group renders a stack of avatars and collapses items beyond max into a +N overflow avatar with an accessible label such as '2 more'.
<div class="avatar-group-example">
<kui-avatar-group [avatars]="members" [max]="4" size="sm" label="Project participants" />
</div>kui-avatar is not clickable itself. Wrap it in a native button when the avatar needs to open a profile or menu.
<div class="avatar-button-example">
<button class="kui-avatar-action" type="button" aria-label="Open Nikita Repin profile">
<kui-avatar src="https://i.pravatar.cc/64?img=12" name="Nikita Repin" />
</button>
</div>Inputs verified against @kikita-labs/ui v1.6.1 public typings.
| Name | Type | Default | Description |
|---|---|---|---|
| src | string | undefined | undefined | Image URL. Falls back to initials, then the icon fallback, on load error. |
| name | string | undefined | undefined | Used to derive initials, the palette hash, and the accessible label. |
| initials | string | undefined | auto | Explicit one or two character initials, overriding the value derived from name. |
| alt | string | undefined | name | Image alt text and accessible label override. |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' | Fixed avatar size. |
| shape | 'circle' | 'square' | 'circle' | circle is intended for people; square is intended for entities such as bots, teams, or projects. |
| status | 'online' | 'away' | 'busy' | 'offline' | undefined | undefined | Optional presence indicator. Appended to the accessible label; the dot itself is decorative. |
| paletteIndex | number | undefined | auto | Palette slot from 1 to 7 used for the fallback background and text color. Clamped when explicit. |
| loading | boolean | false | Renders the avatar using the internal [kuiSkeleton] loading treatment and hides avatar content. |
| kui-avatar-group avatars | readonly KuiAvatarItem[] | [] | Items rendered by the group. Each item accepts the same fields as kui-avatar. |
| kui-avatar-group max | number | 4 | Maximum visible avatars before the group collapses the rest into a +N overflow avatar. |
| kui-avatar-group size | KuiAvatarSize | 'md' | Size applied to every avatar in the group, including the overflow avatar. |
| kui-avatar-group shape | KuiAvatarShape | 'circle' | Shape applied to every avatar in the group, including the overflow avatar. |
| kui-avatar-group label | string | 'Avatar group' | Accessible label for the group container. |
| .kui-avatar-action | CSS class | - | Applied to an external native button wrapping a kui-avatar to make it interactive. kui-avatar itself must not be made clickable. |
Avatar exposes accessible names automatically and keeps interactive behavior on native elements.
- Image avatars render a native
<img>withaltderived fromalt, thenname. - Initials and icon fallback avatars expose
role="img"andaria-label. - Status is appended to the accessible label, for example
Nikita Repin, online. The status dot itself is decorative. - Interactive avatars must use a native
<button class="kui-avatar-action">wrapper with its ownaria-label. Do not makekui-avataritself clickable. - Avatar group overflow exposes a
+Navatar with an accessible label such as2 more.