{"id":15274,"library":"vue-lazyload","title":"Vue-Lazyload","description":"Vue-Lazyload is a Vue.js module designed for efficiently lazy-loading images within Vue 3 applications. As of version 3.0.0, it is specifically tailored for Vue 3, offering a lightweight and powerful solution to improve initial page load performance by deferring image loading until they enter the viewport. It provides a simple directive-based API (`v-lazy`) for individual images and supports managing groups of images within a container using `v-lazy-container`. The library offers customization through options for custom loading and error placeholders, configurable pre-loading distances, and various event listeners. While historical versions targeted Vue 1.x and 2.x, the current major release, v3.0.0, represents a significant shift to Vue 3, necessitating changes in application initialization. The project's release cadence appears to be irregular, with notable intervals between major version updates.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/hilongjw/vue-lazyload","tags":["javascript","vue-lazyload","vue","lazyload","vue-directive","typescript"],"install":[{"cmd":"npm install vue-lazyload","lang":"bash","label":"npm"},{"cmd":"yarn add vue-lazyload","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-lazyload","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer 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.","package":"vue","optional":false}],"imports":[{"note":"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.","wrong":"const VueLazyload = require('vue-lazyload')","symbol":"VueLazyload","correct":"import VueLazyload from 'vue-lazyload'"},{"note":"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 }\">`.","wrong":"<img :src=\"imageSrc\" v-lazy>","symbol":"v-lazy (directive)","correct":"<img v-lazy=\"imageSrc\">"},{"note":"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`.","wrong":"<div v-lazy-container>\n  <img src=\"//example.com/img.jpg\">\n</div>","symbol":"v-lazy-container (directive)","correct":"<div v-lazy-container=\"{ selector: 'img', error: 'error.jpg' }\">\n  <img data-src=\"//example.com/img.jpg\">\n</div>"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport VueLazyload from 'vue-lazyload';\n\n// Import images for placeholders, ensuring they are correctly processed by your bundler\nimport loadingGif from './assets/loading.gif';\nimport errorGif from './assets/error.gif';\n\nconst app = createApp(App);\n\napp.use(VueLazyload, {\n  preLoad: 1.3, // Pre-load 1.3 times the viewport height\n  error: errorGif, // Image to show on error\n  loading: loadingGif, // Image to show while loading\n  attempt: 1 // Number of attempts to load the image\n});\n\napp.mount('#app');\n\n// src/App.vue\n<template>\n  <div>\n    <h1>Lazy Loaded Images</h1>\n    <div v-for=\"n in 100\" :key=\"n\" class=\"image-wrapper\">\n      <img v-lazy=\"`https://picsum.photos/id/${n + 10}/400/300`\" alt=\"Placeholder Image\">\n    </div>\n    <h2>Lazy Loaded Raw HTML Images</h2>\n    <div v-lazy-container=\"{ selector: 'img', error: '/placeholder_error.jpg', loading: '/placeholder_loading.gif' }\" class=\"raw-html-container\">\n      <img data-src=\"https://picsum.photos/id/1000/400/300\" alt=\"Raw HTML Image 1\">\n      <img data-src=\"https://picsum.photos/id/1001/400/300\" alt=\"Raw HTML Image 2\">\n    </div>\n  </div>\n</template>\n\n<style>\n.image-wrapper {\n  height: 300px; /* Give some height for scrolling */\n  margin-bottom: 20px;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n  background-color: #f0f0f0;\n}\nimg {\n  max-width: 100%;\n  height: auto;\n  display: block;\n}\n.raw-html-container img {\n  height: 200px;\n  width: 300px;\n  object-fit: cover;\n  margin: 10px;\n}\n</style>","lang":"typescript","description":"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."},"warnings":[{"fix":"Rewrite Vue application entry point to use `createApp` and pass the app instance to `use(VueLazyload)`.","message":"Vue-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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace `const VueLazyload = require('vue-lazyload')` with `import VueLazyload from 'vue-lazyload'`.","message":"Modern 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Import 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`.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If 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.","message":"The 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.","severity":"gotcha","affected_versions":"<=1.1.1 (prior to Intersection Observer addition), or any version in unsupported browsers"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `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`).","cause":"Vue-Lazyload plugin was not properly installed on the Vue application instance.","error":"TypeError: Cannot read properties of undefined (reading 'directive') OR [Vue warn]: Failed to resolve directive: lazy"},{"fix":"Double-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.","cause":"The image `src` or `data-src` value is incorrect, inaccessible, or the `loading` and `error` placeholders are not resolving.","error":"Image src is blank or broken when using v-lazy"},{"fix":"Verify 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'.","cause":"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.","error":"Images not lazy-loading; all load on page render"}],"ecosystem":"npm"}