{"id":12550,"library":"vue-progressive-image","title":"Vue Progressive Image Loading","description":"The `vue-progressive-image` package provides a plugin for Vue 3 applications, enabling efficient progressive image loading and lazy loading. This approach enhances perceived performance by displaying a low-resolution placeholder that smoothly transitions to the full-resolution image once it has completely loaded. The current stable version, 5.0.6, released in October 2025, indicates active development and maintenance with regular bug fixes. Key differentiators include its deep integration with Vue 3's component and plugin architecture, comprehensive TypeScript support since v5.0.0, and a straightforward API for managing image loading states. The library requires Vue `^3.5.13` as a peer dependency, ensuring compatibility with modern Vue applications and tooling. It focuses on delivering a robust, performant solution for image optimization without complex configuration.","status":"active","version":"5.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/MatteoGabriele/vue-progressive-image","tags":["javascript","progressive","image","img","lazy loading","typescript"],"install":[{"cmd":"npm install vue-progressive-image","lang":"bash","label":"npm"},{"cmd":"yarn add vue-progressive-image","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-progressive-image","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for the Vue plugin and component functionality.","package":"vue","optional":false}],"imports":[{"note":"For global plugin registration with `app.use()`. The default export is the plugin itself. Since v5, the package is ESM-only; CJS `require` will fail.","wrong":"const ProgressiveImage = require('vue-progressive-image');","symbol":"ProgressiveImage","correct":"import ProgressiveImage from 'vue-progressive-image';"},{"note":"While typically registered globally via the plugin, the component might also be directly importable for specific use cases or local registration (check official docs for this pattern if global is not desired).","symbol":"ProgressiveImage","correct":"import { ProgressiveImage } from 'vue-progressive-image/components';"},{"note":"Imports the TypeScript type definition for configuring the plugin's global options, useful for type-safe setup in TypeScript projects.","symbol":"ProgressiveImageOptions","correct":"import type { ProgressiveImageOptions } from 'vue-progressive-image';"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport ProgressiveImage from 'vue-progressive-image';\nimport 'vue-progressive-image/dist/style.css'; // Import base styles if provided by the library\n\nconst app = createApp(App);\n\n// Register the plugin globally with optional default configurations\napp.use(ProgressiveImage, {\n delay: 300, // Time in ms before the high-res image starts loading after intersection\n threshold: 0.2 // Intersection Observer threshold\n});\n\napp.mount('#app');\n\n// --- App.vue ---\n// \n\n// ","lang":"typescript","description":"This quickstart demonstrates how to globally register the `vue-progressive-image` plugin in a Vue 3 application, including optional configuration parameters. It then shows the basic usage of the `` component within a template, configured with placeholder and full-resolution image URLs for progressive loading within a scrollable container."},"warnings":[{"fix":"Review the official v5.0.0 changelog and documentation for specific migration steps. Ensure your build pipeline supports ESM for imports and integrate TypeScript correctly.","message":"Version 5.0.0 introduced significant breaking changes, including migration to TypeScript, a switch from ESLint/Prettier to Biome, and an update to be ESM-only. Applications using previous major versions (v3.x) will require refactoring for type compatibility and module resolution.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure your project is running Vue 3.x. If you need Vue 2 compatibility, you must use an older major version of `vue-progressive-image` (e.g., v3.x).","message":"The peer dependency for Vue has been updated to `^3.5.13`. Versions 5.x are not compatible with Vue 2.x projects. Attempting to use `vue-progressive-image` v5.x with Vue 2 will result in runtime errors.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always use ES module `import` syntax. If encountering `__dirname is not defined` errors during build, ensure your bundler (e.g., Vite, Webpack) is correctly configured to handle ESM and provide shims or alternatives for such Node.js globals if necessary for your environment.","message":"The package transitioned to ESM-only in version 5.0.0. This means CommonJS `require()` statements will fail, and certain Node.js global variables like `__dirname` are not available in the ES module scope, which has caused build issues (e.g., in v5.0.5).","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Update to version 5.0.3 or newer to resolve the `alt` tag issue. Manually ensure `alt` attributes are always provided and correctly rendered on your `ProgressiveImage` components.","message":"While the plugin aims to handle image attributes, a bug in v5.0.3 resulted in placeholder images missing their `alt` tags. Although fixed, always verify accessibility attributes for SEO and user experience.","severity":"gotcha","affected_versions":"<5.0.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project's build configuration (e.g., `vite.config.ts`, `webpack.config.js`) is correctly set up for ES Modules. If you're building for Node.js environments and need `__dirname`, you might need to use `import.meta.url` with `fileURLToPath` and `dirname` from the `path` module for an equivalent path.","cause":"This error occurs because `vue-progressive-image` versions 5.x and above are ESM-only, and `__dirname` is a CommonJS global variable not available in ES module contexts by default.","error":"__dirname is not defined in ES module scope"},{"fix":"Verify that `app.use(ProgressiveImage)` is called in your main application entry file (e.g., `main.ts`). If you intend to register it locally, ensure you are importing `{ ProgressiveImage }` (if exported) and adding it to your component's `components` option or importing directly in a `