Avatar

Headless image component with automatic fallback to icon or text content.

Usage

The Avatar component provides a robust image loading system with automatic fallback handling. It manages multiple image sources with priority ordering and only displays the highest-priority loaded image or fallback content.

Anatomy

<script setup lang="ts">
  import { Avatar } from '@vuetify/v0'
</script>

<template>
  <Avatar.Root>
    <Avatar.Image />

    <Avatar.Fallback />
  </Avatar.Root>
</template>

Architecture

The Avatar uses an internal selection system with mandatory: 'force' to ensure exactly one element is always visible. Images register as disabled until they load successfully.

Loading state slot props

Avatar.Image exposes the underlying loading state from useImage via slot props. Use these for custom transitions, retry UI, or status indicators.

Priority System

When multiple images are present, the priority prop determines display order. Higher priority images are preferred when loaded:

<template>
  <Avatar.Root>
    <!-- Preferred when loaded -->
    <Avatar.Image src="/high-res.jpg" :priority="1" />

    <!-- Fallback image -->
    <Avatar.Image src="/low-res.jpg" :priority="0" />

    <!-- Text fallback -->
    <Avatar.Fallback>JD</Avatar.Fallback>
  </Avatar.Root>
</template>