Vue Progressive Image Loading

5.0.6 · active · verified Sun Apr 19

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.

Common errors

```
__dirname is not defined in ES module scope
```
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.

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.
```
[Vue warn]: Failed to resolve component: ProgressiveImage
```
cause This warning typically appears when the `ProgressiveImage` component is used in a template but has not been properly registered, either globally via `app.use()` or locally in the component where it's being used.

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 `<script setup>` block.

Warnings

breaking 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.
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.
breaking 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.
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).
gotcha 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).
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.
gotcha 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.
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.

Install

npm install vue-progressive-image npm
yarn add vue-progressive-image yarn
pnpm add vue-progressive-image pnpm

Imports

ProgressiveImage
wrong:
```
const ProgressiveImage = require('vue-progressive-image');
```
correct:
```
import ProgressiveImage from 'vue-progressive-image';
```
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.
ProgressiveImage
```
import { ProgressiveImage } from 'vue-progressive-image/components';
```
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).
ProgressiveImageOptions
```
import type { ProgressiveImageOptions } from 'vue-progressive-image';
```
Imports the TypeScript type definition for configuring the plugin's global options, useful for type-safe setup in TypeScript projects.

Quickstart

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.

import { createApp } from 'vue';
import App from './App.vue';
import ProgressiveImage from 'vue-progressive-image';
import 'vue-progressive-image/dist/style.css'; // Import base styles if provided by the library

const app = createApp(App);

// Register the plugin globally with optional default configurations
app.use(ProgressiveImage, {
  delay: 300, // Time in ms before the high-res image starts loading after intersection
  threshold: 0.2 // Intersection Observer threshold
});

app.mount('#app');

// --- App.vue ---
// <template>
//   <div>
//     <h1>Product Gallery</h1>
//     <div style="height: 500px; overflow-y: auto; padding: 20px; border: 1px solid #eee;">
//       <ProgressiveImage
//         src="https://picsum.photos/seed/gallery1/1200/800"
//         placeholder="https://picsum.photos/seed/gallery1/60/40"
//         alt="A serene landscape with mountains and lake"
//         style="width: 100%; max-width: 600px; display: block; margin-bottom: 30px; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);"
//       />
//       <ProgressiveImage
//         src="https://picsum.photos/seed/gallery2/1000/700"
//         placeholder="https://picsum.photos/seed/gallery2/50/35"
//         alt="City skyline at sunset with vibrant colors"
//         style="width: 100%; max-width: 600px; display: block; margin-bottom: 30px; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);"
//       />
//       <ProgressiveImage
//         src="https://picsum.photos/seed/gallery3/900/1200"
//         placeholder="https://picsum.photos/seed/gallery3/45/60"
//         alt="Close-up of a blooming flower with dew drops"
//         style="width: 100%; max-width: 400px; display: block; margin-bottom: 30px; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);"
//       />
//     </div>
//   </div>
// </template>

// <script setup lang="ts">
// // No explicit component import needed in script setup if registered globally
// </script>

view raw JSON →