Components
Avatar
Display a user image or initials with optional mask shapes.
UiAvatar shows an image (src) or falls back to initials, with an optional decorative maskShape.
Add an avatar
<template>
<UiAvatar src="/users/jane.jpg" alt="Jane Doe" size="md" />
<UiAvatar initials="JD" size="lg" />
</template>
Apply a mask shape
<template>
<UiAvatar src="/users/jane.jpg" mask-shape="gem" />
<UiAvatar initials="GG" mask-shape="cookie-9" mask-stretch />
</template>
Show a status indicator
Set status to render a small presence dot on the avatar's bottom-end corner. The dot scales with the avatar size and is ringed with the surface color so it reads on any background.
<template>
<UiAvatar src="/users/jane.jpg" status="online" />
<UiAvatar initials="JD" status="busy" />
<UiAvatar src="/users/jane.jpg" mask-shape="gem" status="away" />
</template>
| Status | Color token |
|---|---|
online | --theme-success-base |
busy | --theme-danger-base |
away | --theme-warning-base |
offline | --theme-muted-a10 |
When
status is set, the avatar is wrapped in an .avatar-status-wrapper element so the dot is not clipped by maskShape masks — with a mask, the dot is also nudged inward to stay over the visible shape. UiAvatarGroup styles account for this wrapper, so status avatars can be mixed into groups. Without status, the rendered markup is unchanged.Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | — | Image URL. |
alt | string | 'Avatar' | Accessible name. |
initials | string | null | — | Fallback initials when no image is set. |
size | 'sm' | 'md' | 'lg' | 'navbar' | 'menu' | — | Avatar size. |
maskShape | 'arch' | 'pill' | 'sunny' | 'gem' | 'cookie-6' | 'cookie-9' | 'cookie-12' | 'clover-4' | 'clover-8' | 'bum' | null | — | Decorative mask. |
maskStretch | boolean | false | Stretch the mask to 115%. |
status | 'online' | 'busy' | 'away' | 'offline' | null | — | Presence indicator dot on the avatar's bottom-end corner. |
Avatar Group
UiAvatarGroup stacks avatars with an overlapping ring, either from an avatars array or by composing UiAvatar instances via the default slot.
Stack avatars from a list
<script setup lang="ts">
const team = [
{ initials: 'JD' },
{ initials: 'AS' },
{ initials: 'MK' },
]
</script>
<template>
<UiAvatarGroup :avatars="team" />
</template>
Collapse overflow with max
Set max to cap the visible avatars; the remainder collapses into a "+N" avatar styled like the initials fallback.
<template>
<UiAvatarGroup :avatars="team" :max="3" />
</template>
max only applies to the avatars prop. When composing UiAvatar instances via the default slot, all of them render — cap the array yourself before passing it to the slot.Compose with the default slot
<template>
<UiAvatarGroup>
<UiAvatar initials="JD" size="md" />
<UiAvatar initials="AS" size="md" />
<UiAvatar initials="MK" size="md" />
</UiAvatarGroup>
</template>
UiAvatarGroup props
| Prop | Type | Default | Description |
|---|---|---|---|
avatars | IAvatarProps[] | — | Avatars to render, in order. Alternative to composing UiAvatar via the default slot. |
max | number | — | Caps the rendered avatars, collapsing the remainder into a "+N" overflow avatar. Only applies to the avatars prop. |
size | 'sm' | 'md' | 'lg' | 'navbar' | 'menu' | 'sm' | Size applied to every avatar in the group (and the overflow avatar). Individual avatars entries can override it. |
customClass | string | string[] | Record<string, boolean> | null | — | Extra classes for the group container. |
Slots: default — compose UiAvatar instances directly instead of passing avatars.