useImage
Tracks image loading state as a reactive state machine with idle, loading, loaded, and error states.
Usage
The useImage composable owns the loading lifecycle for a single image source. Bind the returned source, onLoad, and onError to a plain image element.
<script setup lang="ts">
import { toRef } from 'vue'
import { useImage } from '@vuetify/v0'
const props = defineProps<{ src: string, alt: string }>()
const { source, isLoaded, isError, onLoad, onError, retry } = useImage({
src: toRef(() => props.src),
})
</script>
<template>
<img
:alt
:src="source"
@load="onLoad"
@error="onError"
>
</template>Architecture
Reactivity
| Property/Method | Reactive | Notes |
|---|---|---|
status | Readonly ShallowRef of 'idle' | 'loading' | 'loaded' | 'error' | |
isIdle / isLoading / isLoaded / isError | Readonly boolean refs derived from status | |
source | Gated src — undefined while idle, otherwise the current source | |
onLoad / onError | Bind to image load / error events | |
retry | Reset back to loading and re-attempt |
Examples
FAQ
eager is a reactive gate that mirrors the semantics of HTML’s loading="eager" attribute — when eager is true, the image starts loading. When false, the source is withheld and status stays idle. Using eager lets you write expressive bindings like eager: isIntersecting.
No. useImage is the state machine; viewport detection is a separate concern. Compose it with useIntersectionObserver (or any other reactive gate) by passing the result to the eager option.
Native browser-level lazy loading is a separate mechanism. The browser still fires load and error events, so useImage works correctly with or without it. Reach for the eager gate only when you need to control exactly when the source is set.
Status resets to loading (or idle if eager is false) and the source updates. Already-loaded or errored states do not persist across source changes.
So you can bind it directly to an <img> element without the browser starting a request. The browser ignores <img> elements without a src, which is exactly what you want during the deferred phase.