Avatar

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>

Color initials and placeholders

Initials and placeholder avatars use a light accent tint by default. Set color to tint them with any theme color instead. Image avatars ignore it.

<template>
  <UiAvatar initials="JD" color="secondary" />
  <UiAvatar initials="AS" color="success" mask-shape="gem" />
</template>

The tint is the theme color's fixed tone at 25% opacity, so it reads the same in light and dark mode.

Set variant to change how the color is applied:

• transparent (default): the light tint, letting what's behind show through.
• tonal: the same light tint, opaque. Use it where avatars overlap other content.
• filled: the full theme color with contrasting text.

<template>
  <UiAvatar initials="JD" color="primary" variant="tonal" />
  <UiAvatar initials="AS" color="primary" variant="filled" />
</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>

Props

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>

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

Slots: default — compose UiAvatar instances directly instead of passing avatars.

CSS variables

Set these on :root, or on any wrapper to restyle only the avatars inside it. --cffy-avatar-tint-color applies when no color is set; the color prop keeps its own tint. Mask shapes replace the radius, and the navbar initials keep their small corners.

:root {
  --cffy-avatar-radius: var(--cffy-radius-lg);
  --cffy-avatar-status-online-color: var(--cffy-info-base);
}