Avatar

A headless component for managing image loading with priority-based fallback system.

Copy Page as Markdown

Renders elementIntermediate100% coverageJan 27, 2026

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.

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

<template>
  <div class="flex gap-4">
    <Avatar.Root class="w-12 h-12 rounded-full flex items-center justify-center overflow-hidden bg-surface-tint">
      <Avatar.Image
        class="w-full h-full object-cover"
        src="https://i.pravatar.cc/150?img=1"
      />

      <Avatar.Fallback class="text-sm font-semibold text-secondary">
        JD
      </Avatar.Fallback>
    </Avatar.Root>

    <Avatar.Root class="w-12 h-12 rounded-full flex items-center justify-center overflow-hidden bg-surface-tint">
      <Avatar.Image
        class="w-full h-full object-cover"
        src="/invalid.jpg"
      />

      <Avatar.Fallback class="text-sm font-semibold text-secondary">
        FB
      </Avatar.Fallback>
    </Avatar.Root>
  </div>
</template>

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.

Priority System

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

vue

<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>

Default: "v0:avatar"

Default: 0

namespace

string

Namespace for retrieving avatar context

Default: "v0:avatar"

Avatar

Usage

Anatomy

Architecture

Priority System

API Reference

Avatar.Root

Props

namespace

Slots

default

Avatar.Fallback

Props

namespace

Slots

default

Avatar.Image

Props

src

priority

namespace

Events

load

error

Slots

default