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.
npm install vue-progressive-imageVerified import paths — ran on the pinned version, not inferred.
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 `<ProgressiveImage>` component within a template, configured with placeholder and full-resolution image URLs for progressive loading within a scrollable container.
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.
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).
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.
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.
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.
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 `<script setup>` block.