Overview
Avatar provides a robust image display system with automatic fallback logic. It uses an internal selection system with mandatory: 'force' to ensure one item is always visible. Images register with priority values and the highest-priority loaded image is displayed.
Sub-Components
- Avatar.Root: Container that manages image loading state and fallback logic
- Avatar.Image: Image component with automatic show/hide based on load state
- Avatar.Fallback: Fallback content shown when no images are loaded
Usage
<script lang="ts" setup>
import { Avatar } from '@vuetify/v0'
</script>
<template>
<Avatar.Root>
<Avatar.Image src="/avatar.jpg" />
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
</template>
Avatar.Root
Props
as
DOMElement | null
default:"'div'"
The HTML element to render as
Render without a wrapper element
namespace
string
default:"'v0:avatar'"
Namespace for dependency injection
Slots
Content slot for Avatar.Image and Avatar.Fallback components
Avatar.Image
Props
as
DOMElement | null
default:"'img'"
The HTML element to render as
Priority for display order (higher = more preferred)
namespace
string
default:"'v0:avatar'"
Namespace for retrieving avatar context
Events
Emitted when image successfully loads
Emitted when image fails to load
Slot Props
Whether this image is currently visible
Attributes to bind to the image element including role, src, onLoad, and onError
Avatar.Fallback
Props
as
DOMElement | null
default:"'span'"
The HTML element to render as
namespace
string
default:"'v0:avatar'"
Namespace for retrieving avatar context
Slot Props
Whether this fallback is currently visible
Examples
<script setup>
import { Avatar } from '@vuetify/v0'
</script>
<template>
<Avatar.Root>
<Avatar.Image src="/avatar.jpg" />
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
</template>
<template>
<Avatar.Root as="figure">
<Avatar.Image src="/avatar.jpg" />
<Avatar.Fallback as="figcaption">JD</Avatar.Fallback>
</Avatar.Root>
</template>
<template>
<Avatar.Root>
<!-- High-res image with higher priority -->
<Avatar.Image
src="/avatar-hd.jpg"
:priority="10"
/>
<!-- Standard image with lower priority -->
<Avatar.Image
src="/avatar.jpg"
:priority="5"
/>
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
</template>
<script setup>
import { Avatar } from '@vuetify/v0'
function handleLoad(e: Event) {
console.log('Image loaded', e)
}
function handleError(e: Event) {
console.log('Image failed to load', e)
}
</script>
<template>
<Avatar.Root>
<Avatar.Image
src="/avatar.jpg"
@load="handleLoad"
@error="handleError"
/>
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
</template>
<script setup>
import { Avatar } from '@vuetify/v0'
</script>
<template>
<Avatar.Root>
<Avatar.Image src="/avatar.jpg" renderless>
<template #default="{ attrs }">
<img v-bind="attrs" class="custom-img" />
</template>
</Avatar.Image>
<Avatar.Fallback renderless>
<template #default="{ isSelected }">
<div v-if="isSelected" class="custom-fallback">
JD
</div>
</template>
</Avatar.Fallback>
</Avatar.Root>
</template>
<template>
<!-- Isolated avatar contexts -->
<Avatar.Root namespace="avatar-1">
<Avatar.Fallback namespace="avatar-1">A1</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root namespace="avatar-2">
<Avatar.Fallback namespace="avatar-2">A2</Avatar.Fallback>
</Avatar.Root>
</template>
Accessibility
Avatar.Image automatically sets role="img" for accessibility:
<template>
<Avatar.Root>
<Avatar.Image src="/avatar.jpg" alt="User avatar" />
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
</template>
SSR
Avatar is fully compatible with SSR. On the server, the fallback will be rendered by default since images cannot load:
<template>
<Avatar.Root>
<Avatar.Image src="/avatar.jpg" />
<Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
</template>
