Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Display

Avatar

An image that shows your fallback content while loading or when the image fails.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

sm Ana Martins avatarmd Ana Martins avatarlg Ana Martins avatar

Install

Run in your project
bunx --bun @getweini/cli@latest add avatar

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Ada Lovelace
Vue
<script setup lang="ts">
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarImage from './components/ui/avatar/AvatarImage.vue'

const portrait =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="#e4e4e7"/><text x="32" y="41" text-anchor="middle" font-family="sans-serif" font-size="26" fill="#27272a">AL</text></svg>',
  )
</script>

<template>
  <Avatar size="lg">
    <AvatarImage :src="portrait" alt="Ada Lovelace" />
    <AvatarFallback aria-hidden="true">AL</AvatarFallback>
  </Avatar>
</template>

The fallback remains visible until the image loads and after errors. Use meaningful alt text, or alt="" for decorative images; hide a fallback that repeats adjacent text from assistive technology.

When to use it

Team directory

Display a person’s image alongside their name and role.

Participant list

Show initials immediately while remote profile images load.

More examples

Named team member

The image and text together identify the person.

Named team member
<script setup lang="ts">
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarImage from './components/ui/avatar/AvatarImage.vue'

const portrait =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="#e4e4e7"/><text x="32" y="41" text-anchor="middle" font-family="sans-serif" font-size="26" fill="#27272a">AL</text></svg>',
  )
</script>

<template>
  <div class="flex items-center gap-3">
    <Avatar>
      <AvatarImage :src="portrait" alt="" />
      <AvatarFallback aria-hidden="true">AL</AvatarFallback>
    </Avatar>
    <span>Ada Lovelace, engineer</span>
  </div>
</template>

Rounded project image

Use a non-circular shape for an entity such as a project.

Rounded project image
<script setup lang="ts">
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarImage from './components/ui/avatar/AvatarImage.vue'

const portrait =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="#e4e4e7"/><text x="32" y="41" text-anchor="middle" font-family="sans-serif" font-size="26" fill="#27272a">AT</text></svg>',
  )
</script>

<template>
  <Avatar shape="rounded" size="lg">
    <AvatarImage :src="portrait" alt="Atlas project" />
    <AvatarFallback>AT</AvatarFallback>
  </Avatar>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Avatar

Complete API for Avatar
NameType or signatureDefaultWhat it does
sizeprop"sm" | "md" | "lg" | undefinedNot setInherits from a parent AvatarGroup, or defaults to `md` when standalone.
shapeprop"circle" | "rounded" | "square" | undefinedNot setInherits from a parent AvatarGroup, or defaults to `circle` when standalone.
defaultslot() => unknownRequiredContent shown inside Avatar.
elementexposedHTMLElement | null—Reference to the underlying HTML element.

AvatarFallback

Complete API for AvatarFallback
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside AvatarFallback.

AvatarImage

Complete API for AvatarImage
NameType or signatureDefaultWhat it does
srcpropstringRequiredURL of the image or media to display.
altpropstringRequiredDescribe this image when it cannot be seen.
Public type definitions
Public types
// packages/frameworks/vue/components/avatar/types.ts
// ------- IMPORTS -------

import type { avatarShapes, avatarSizes } from './styles'

// ------- TYPES -------

export interface AvatarProps {
  /** Inherits from a parent AvatarGroup, or defaults to `md` when standalone. */
  size?: keyof typeof avatarSizes
  /** Inherits from a parent AvatarGroup, or defaults to `circle` when standalone. */
  shape?: keyof typeof avatarShapes
}

export interface AvatarImageProps {
  src: string
  alt: string
}


// packages/frameworks/vue/components/avatar/styles.ts
// Change Avatar size and shape here; the public visual types follow these keys.
export const avatarSizes = {
  sm: 'size-8 text-xs',
  md: 'size-10 text-sm',
  lg: 'size-12 text-base',
} as const

export const avatarShapes = {
  circle: 'rounded-full',
  rounded: 'rounded-ui',
  square: 'rounded-none',
} as const

Implementation notes

  • The fallback is shown while the image loads and if loading fails.
  • Use stable initials or a short project abbreviation as the fallback.

Accessibility and localization

  • Use alt="" when adjacent text already names the same person; use descriptive alt when the image is the only identifier.

Source contract and editing guidance