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 { KuiAvatar, KuiAvatarGroup } 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>Set defaults.avatar once for the application or for a subtree. Each option resolves as local input > defaults.avatar.<option> > built-in default.
import { provideKikitaUi } from '@kikita-labs/ui';
export const appConfig: ApplicationConfig = {
providers: [
provideKikitaUi({
defaults: {
avatar: {
/* options below */
},
},
}),
],
};| Name | Type | Default | Description |
|---|---|---|---|
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | — | Component size. Takes precedence over the global defaults.size. |
| shape | 'circle' | 'square' | — | Default shape. |
| Name | Type | Default | Description |
|---|---|---|---|
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | — | Component size. Takes precedence over the global defaults.size. |
| shape | 'circle' | 'square' | — | Default shape. |
| max | number | — | Maximum avatars shown before the overflow counter. |
Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.
| Name | Type | Default | Description |
|---|---|---|---|
| --kui-avatar-status-radius | CSS custom property | --kui-radius-full | Status corner radius |
Every text the component owns (accessible names, visible words, announcements) is a typed message with an English default. Override it for the application with provideKikitaUi({ messages }), or for a subtree with provideKuiMessages.
The status words are appended to the accessible name of an avatar with a status, and the group label and overflow text come from the avatarGroup messages. The label input of the group is undefined when omitted.
provideKikitaUi({
messages: {
avatar: { statusOnline: 'available' },
avatarGroup: { overflow: ({ count }) => '+' + count },
},
});| Name | Type | Default | Description |
|---|---|---|---|
| fallback | string | — | Name used when the avatar has no alt, name or initials. Default Avatar. |
| statusOnline | string | — | Status word for online. Default online. |
| statusAway | string | — | Status word for away. Default away. |
| statusBusy | string | — | Status word for busy. Default busy. |
| statusOffline | string | — | Status word for offline. Default offline. |
| withStatus | KuiMessageFn<{ label: string; status: string; }> | — | Name with its status appended. Default {label}, {status}. |
| Name | Type | Default | Description |
|---|---|---|---|
| label | string | — | Accessible name of the group. Default Avatar group. |
| overflow | KuiMessageFn<{ count: number; }> | — | Overflow chip text. Default {count} more. |
Inputs, provider defaults, messages and tokens verified against @kikita-labs/ui v2.0.0 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. Falls back to defaults.avatar.size, then the global defaults.size. |
| shape | 'circle' | 'square' | 'circle' | circle is intended for people; square is intended for entities such as bots, teams, or projects. Falls back to defaults.avatar.shape. |
| 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. A static numeric attribute is coerced and finite values clamp to 1-7. |
| 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. Falls back to defaults.avatarGroup.max; a static numeric attribute is coerced, and an invalid or less-than-one value resolves to 1. |
| kui-avatar-group size | KuiAvatarSize | 'md' | Size applied to every avatar in the group, including the overflow avatar. Falls back to defaults.avatarGroup.size, then the global defaults.size. |
| kui-avatar-group shape | KuiAvatarShape | 'circle' | Shape applied to every avatar in the group, including the overflow avatar. Falls back to defaults.avatarGroup.shape. |
| kui-avatar-group label | string | undefined | 'Avatar group' | Accessible label for the group container. Undefined when omitted: the rendered text comes from the avatarGroup.label message. |
| .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. |
| KuiAvatarItem | interface | - | Item of kui-avatar-group avatars: the same fields as kui-avatar (src, name, initials, alt, status, paletteIndex). |
| KuiAvatarOptions / KuiAvatarGroupOptions | interfaces | - | Shapes of defaults.avatar (size, shape) and defaults.avatarGroup (size, shape, max). |
| KuiAvatarMessages / KuiAvatarGroupMessages | interfaces | - | Typed messages of the avatar (fallback name, status words, name with status) and of the group (label, overflow text). |
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.
Consumer-visible changes of @kikita-labs/ui 2.0 for avatars.
- The classes are
KuiAvatarandKuiAvatarGroup(they had aComponentsuffix).ng update @kikita-labs/uirenames the imports. - Size, shape and the group's maximum come from
defaults.avataranddefaults.avatarGroup; the inputs are undefined when omitted. - Static numeric attributes (
paletteIndex,max) are coerced, and an invalid group maximum falls back to a safe value instead of reaching the markup. - Avatar text moved to messages, so translations go through the
messagesoption ofprovideKikitaUiinstead of per-instance inputs.