Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VueLazyload
✓ import VueLazyload from 'vue-lazyload'
✗ const VueLazyload = require('vue-lazyload')
For Vue 3, `VueLazyload` is the default export and should be imported using ESM syntax. CommonJS `require` is not typically used in modern Vue 3 applications.
v-lazy (directive)
✓ <img v-lazy="imageSrc">
✗ <img :src="imageSrc" v-lazy>
The `v-lazy` directive replaces the `src` attribute. Using both will cause incorrect behavior. For dynamic loading/error images, pass an object: `<img v-lazy="{ src: imageSrc, loading: loadingImg, error: errorImg }">`.
v-lazy-container (directive)
✓ <div v-lazy-container="{ selector: 'img', error: 'error.jpg' }">
<img data-src="//example.com/img.jpg">
</div>
✗ <div v-lazy-container>
<img src="//example.com/img.jpg">
</div>
Used for lazy-loading raw HTML `<img>` tags within a container. It requires a `selector` option to identify the images and images must use `data-src` instead of `src`.
This quickstart demonstrates how to initialize Vue-Lazyload in a Vue 3 application using TypeScript, including global options and examples for the `v-lazy` directive on Vue components and `v-lazy-container` for raw HTML images.
import { createApp } from 'vue';
import App from './App.vue';
import VueLazyload from 'vue-lazyload';
// Import images for placeholders, ensuring they are correctly processed by your bundler
import loadingGif from './assets/loading.gif';
import errorGif from './assets/error.gif';
const app = createApp(App);
app.use(VueLazyload, {
preLoad: 1.3, // Pre-load 1.3 times the viewport height
error: errorGif, // Image to show on error
loading: loadingGif, // Image to show while loading
attempt: 1 // Number of attempts to load the image
});
app.mount('#app');
// src/App.vue
<template>
<div>
<h1>Lazy Loaded Images</h1>
<div v-for="n in 100" :key="n" class="image-wrapper">
<img v-lazy="`https://picsum.photos/id/${n + 10}/400/300`" alt="Placeholder Image">
</div>
<h2>Lazy Loaded Raw HTML Images</h2>
<div v-lazy-container="{ selector: 'img', error: '/placeholder_error.jpg', loading: '/placeholder_loading.gif' }" class="raw-html-container">
<img data-src="https://picsum.photos/id/1000/400/300" alt="Raw HTML Image 1">
<img data-src="https://picsum.photos/id/1001/400/300" alt="Raw HTML Image 2">
</div>
</div>
</template>
<style>
.image-wrapper {
height: 300px; /* Give some height for scrolling */
margin-bottom: 20px;
display: flex;
justify-content: center;
align-items: center;
background-color: #f0f0f0;
}
img {
max-width: 100%;
height: auto;
display: block;
}
.raw-html-container img {
height: 200px;
width: 300px;
object-fit: cover;
margin: 10px;
}
</style>
Debug
Known issues
breakingVue-Lazyload v3.0.0 is built exclusively for Vue 3. Projects migrating from Vue 2 (which used vue-lazyload v1.x) must update their application initialization logic from `new Vue({ ... })` and `Vue.use(VueLazyload)` to the Vue 3 `createApp` instance API (e.g., `createApp(App).use(VueLazyload)`). The global Vue instance is no longer directly mutable.fixRewrite Vue application entry point to use `createApp` and pass the app instance to `use(VueLazyload)`.
affects: >=3.0.0
breakingModern Vue 3 applications and `vue-lazyload` v3.x are designed for ES Modules (`import`). Using CommonJS `require('vue-lazyload')` directly will likely lead to module resolution errors or unexpected behavior in standard Vue CLI/Vite setups. Ensure you use `import` statements.fixReplace `const VueLazyload = require('vue-lazyload')` with `import VueLazyload from 'vue-lazyload'`. affects: >=3.0.0
gotchaWhen providing `loading` and `error` image paths as plugin options (e.g., in `main.ts`), ensure they are correctly resolved by your build tool (Webpack, Vite). Simple string literals for relative paths might not be processed correctly unless explicitly imported or served from a static public folder.fixImport placeholder images: `import loadingGif from './assets/loading.gif';` and then use `loading: loadingGif`. Alternatively, place images in your public folder and use root-relative paths like `/images/loading.gif`.
affects: >=1.0.0
gotchaThe library leverages `IntersectionObserver` for efficient lazy loading when available. In environments lacking native `IntersectionObserver` support (e.g., older browsers like IE or some specific WebViews), it falls back to less performant scroll event listening. This can lead to less precise loading or decreased performance.fixIf supporting older browsers is critical, consider adding a polyfill for `IntersectionObserver` (e.g., `intersection-observer`) to ensure consistent performance and behavior across all target environments.
affects: <=1.1.1 (prior to Intersection Observer addition), or any version in unsupported browsers
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'directive') OR [Vue warn]: Failed to resolve directive: lazy
Vue-Lazyload plugin was not properly installed on the Vue application instance.
fixEnsure `app.use(VueLazyload, options)` is called after `createApp(App)` and before `app.mount('#app')` in your Vue 3 application's entry file (e.g., `main.ts`). Image src is blank or broken when using v-lazy
The image `src` or `data-src` value is incorrect, inaccessible, or the `loading` and `error` placeholders are not resolving.
fixDouble-check image paths for `v-lazy` and ensure that placeholder images defined in plugin options (`loading`, `error`) are correctly imported or provided with absolute/root-relative paths that your build system can resolve. For `v-lazy-container`, ensure `data-src` is used on `<img>` tags.
Images not lazy-loading; all load on page render
The `listenEvents` option might be misconfigured, `IntersectionObserver` is not working/polyfilled, or the images are already in the viewport due to small content or incorrect `preLoad` value.
fixVerify that `preLoad` is set to a reasonable value (default is 1.3). Ensure there is enough scrollable content for images to be initially off-screen. If targeting older browsers, ensure `IntersectionObserver` is polyfilled. Check the `listenEvents` array in the options for any missing critical events like 'scroll'.
Audit
Dependencies
vuerequiredPeer dependency, specifically Vue 3.x for versions >= 3.0.0. Older versions (1.x, 2.x) of vue-lazyload supported Vue 1.x/2.x respectively.