Skip to main content

​
Usage

The Avatar component displays user profile images with automatic fallback to initials or icons when images fail to load. 
<template>
  <UAvatar src="/avatar.jpg" alt="John Doe" />
</template>

​
Props

​
as
any | { root?: any, img?: any }
default:"'span'"
The element or component this component should render as. Can be a string/component for the root, or an object with root and img properties to customize both elements.
​
src
string
The source URL of the avatar image.
​
alt
string
Alternative text for the image. Also used to generate fallback initials.
​
icon
string
Icon name to display as fallback instead of initials. Supports any Iconify icon.
​
text
string
Custom text to display as fallback. Overrides the initials generated from alt.
​
size
'3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'
default:"'md'"
The size of the avatar.
​
chip
boolean | ChipProps
Display a chip (notification badge) on the avatar. Pass true for default styling or an object with ChipProps for customization.
​
class
any
Additional CSS classes to apply.
​
style
any
Inline styles to apply.
​
ui
object
UI customization object for styling avatar slots (root, image, icon, fallback).

​
Slots

​
default
{}
Custom content to display inside the avatar. Overrides the default image/icon/text fallback behavior.

​
Examples

​
Basic Avatar

<template>
  <UAvatar src="https://i.pravatar.cc/150?img=1" alt="Jane Cooper" />
</template>

​
Sizes

<template>
  <div class="flex items-center gap-2">
    <UAvatar size="3xs" src="/avatar.jpg" alt="User" />
    <UAvatar size="2xs" src="/avatar.jpg" alt="User" />
    <UAvatar size="xs" src="/avatar.jpg" alt="User" />
    <UAvatar size="sm" src="/avatar.jpg" alt="User" />
    <UAvatar size="md" src="/avatar.jpg" alt="User" />
    <UAvatar size="lg" src="/avatar.jpg" alt="User" />
    <UAvatar size="xl" src="/avatar.jpg" alt="User" />
    <UAvatar size="2xl" src="/avatar.jpg" alt="User" />
    <UAvatar size="3xl" src="/avatar.jpg" alt="User" />
  </div>
</template>

​
Fallback to Initials

When an image fails to load or is not provided, the avatar displays initials from the alt prop: 
<template>
  <UAvatar alt="John Doe" />
  <!-- Displays "JD" -->
</template>

​
Custom Fallback Text

<template>
  <UAvatar text="AB" />
</template>

​
Icon Fallback

<template>
  <UAvatar icon="i-heroicons-user" />
</template>

​
With Chip (Status Badge)

<template>
  <UAvatar 
    src="/avatar.jpg" 
    alt="Jane Cooper" 
    :chip="true" 
  />
</template>

​
Custom Chip

<template>
  <UAvatar 
    src="/avatar.jpg" 
    alt="Jane Cooper" 
    :chip="{ color: 'green', position: 'bottom-right' }" 
  />
</template>

​
Custom Content

<template>
  <UAvatar>
    <img src="/custom-avatar.svg" alt="Custom" />
  </UAvatar>
</template>

​
As Different Elements

<template>
  <!-- Render as a div -->
  <UAvatar as="div" src="/avatar.jpg" alt="User" />
  
  <!-- Customize both root and img elements -->
  <UAvatar 
    :as="{ root: 'div', img: 'img' }" 
    src="/avatar.jpg" 
    alt="User" 
  />
</template>

​
Avatar Group Integration

When used inside an AvatarGroup, the avatar automatically inherits the group’s size: 
<template>
  <UAvatarGroup size="lg">
    <UAvatar src="/avatar1.jpg" alt="User 1" />
    <UAvatar src="/avatar2.jpg" alt="User 2" />
    <UAvatar src="/avatar3.jpg" alt="User 3" />
  </UAvatarGroup>
</template>

​
Notes

  • The avatar automatically generates initials from the alt prop by taking the first character of each word (up to 2 characters)
  • Image loading errors are handled gracefully with automatic fallback to initials or icons
  • Size dimensions (in pixels): 3xs=16, 2xs=20, xs=24, sm=28, md=32, lg=36, xl=40, 2xl=44, 3xl=48

Build docs developers (and LLMs) love

Get started for freeTalk to us