The VImg component is a powerful image container that handles loading states, aspect ratios, lazy loading, and provides slots for customization.
<template>
<v-img
src="https://picsum.photos/500/300"
alt="Sample Image"
cover
/>
</template>
The image source URL or source object with src, srcset, and lazySrc properties.
Alt text for the image (important for accessibility).
Resizes the image to cover the entire container (object-fit: cover).
Calculated as width/height. Forces the image to maintain a specific aspect ratio.
Low-resolution image to display while the main image loads.
Forces the image to load immediately instead of lazy loading.
CSS gradient overlay applied on top of the image.
CSS object-position value for the image.
The sizes attribute for responsive images.
The srcset attribute for responsive images.
crossorigin
'' | 'anonymous' | 'use-credentials'
The crossorigin attribute for CORS.
The referrerpolicy attribute for the image.
draggable
boolean | 'true' | 'false'
Controls whether the image is draggable.
Positions the image absolutely within its container.
Background color displayed while the image is loading.
Options passed to the Intersection Observer for lazy loading.
The transition to use when the image loads.
Emitted when the image starts loading.
Emitted when the image has finished loading.
Emitted when the image fails to load.
Default content displayed over the image.
Content displayed while the image is loading.
Content displayed when the image fails to load.
Slot for adding source elements for the picture element.
Examples
Aspect Ratio
<template>
<v-img
src="https://picsum.photos/1920/1080"
aspect-ratio="16/9"
/>
</template>
Lazy Loading with Placeholder
<template>
<v-img
src="https://picsum.photos/500/300"
lazy-src="https://picsum.photos/10/6"
>
<template #placeholder>
<div class="d-flex align-center justify-center fill-height">
<v-progress-circular indeterminate />
</div>
</template>
</v-img>
</template>
With Gradient
<template>
<v-img
src="https://picsum.photos/500/300"
gradient="to top right, rgba(100,115,201,.33), rgba(25,32,72,.7)"
cover
>
<div class="fill-height d-flex align-end">
<h2 class="text-white pa-4">Gradient Overlay</h2>
</div>
</v-img>
</template>
Error Handling
<template>
<v-img
src="invalid-url.jpg"
@error="handleError"
>
<template #error>
<div class="d-flex align-center justify-center fill-height">
<v-icon size="64" color="error">mdi-image-broken</v-icon>
</div>
</template>
</v-img>
</template>
<script setup>
function handleError(src) {
console.error('Failed to load image:', src)
}
</script>
Responsive Images
<template>
<v-img
src="image-800.jpg"
srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
sizes="(max-width: 600px) 400px, (max-width: 960px) 800px, 1200px"
/>
</template>
Picture Element with Sources
<template>
<v-img src="fallback.jpg">
<template #sources>
<source srcset="image.webp" type="image/webp">
<source srcset="image.jpg" type="image/jpeg">
</template>
</v-img>
</template>