Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/1TSnakers/ProgressiveImageLoader/llms.txt

Use this file to discover all available pages before exploring further.

The ProgressiveImageLoader constructor accepts a single configuration object and immediately begins loading images into the specified container, starting with the lowest-quality image and swapping in higher-quality versions as they finish downloading. It is written in pure vanilla JavaScript with zero dependencies and works in any modern browser without a build step.

​
Including the Library

Before instantiating the loader, add the script to your HTML page. Place the <script> tag before any code that references ProgressiveImageLoader: 
<script src="progressive-image-loader.js"></script>

​
Constructor Signature

new ProgressiveImageLoader({
  container,    // required — HTMLElement
  images,       // required — string[]
  width,        // optional — number (pixels)
  height,       // optional — number (pixels)
  fadeDuration, // optional — number (milliseconds)
  disableCache  // optional — boolean
});

​
Parameters

The constructor takes a single plain object. All fields are listed below.
​
container
HTMLElement
required
The DOM element into which the progressive image will be rendered. The loader appends an <img> element as a child of this container and replaces its src each time a higher-quality image finishes loading.
container: document.getElementById("image-container")
​
images
string[]
required
An array of image path strings ordered from least to most quality. The first entry is displayed immediately while subsequent images are fetched in the background. Every string in the array should be a valid URL or a path resolvable by the browser relative to the HTML document.
images: [
  "bad-image.png",   // shown first — lowest quality
  "mid-image.png",
  "good-image.png"   // shown last — highest quality
]
The array must run from worst to best quality. If you are using the image_ruiner.py companion script, the generated image_list.js file already exports images in the correct order (most degraded first, original last).
​
width
number
Display width in pixels applied directly to the width attribute of the rendered <img> element. When omitted, no explicit width is set and the image renders at its natural size (or whatever your CSS dictates).
width: 600
​
height
number
Display height in pixels applied directly to the height attribute of the rendered <img> element. When omitted, no explicit height is set. You can specify width alone and let the browser maintain the aspect ratio.
height: 400
​
fadeDuration
number
Duration in milliseconds for the CSS fade transition that plays each time the loader swaps in a higher-quality image. A value of 500 produces a gentle half-second crossfade; a value of 0 makes transitions instant.
fadeDuration: 500
Set fadeDuration: 0 when you want snappy, instant quality upgrades without any visual transition — useful for debugging or when your design calls for hard cuts between quality levels.
​
disableCache
boolean
When true, a unique query parameter is appended to each image URL before it is requested, preventing the browser from serving a cached version. This is particularly useful during development when you are regenerating images frequently and want to guarantee the freshest version is always fetched.
disableCache: true
Enabling disableCache in production means every image request will be treated as a cache miss by the browser. This increases bandwidth usage and can slow page loads for returning visitors. Leave it set to false (or omit it) in production.

​
Full Usage Example

The following snippet mirrors the usage shown in the project demo page. It imports a pre-generated image list from the companion script and passes it straight to the loader: 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Progressive Image Loader Demo</title>
</head>
<body>
  <!-- Container for the progressive image -->
  <div id="image-container"></div>

  <!-- Include the library -->
  <script src="progressive-image-loader.js"></script>

  <script>
    new ProgressiveImageLoader({
      container: document.getElementById("image-container"),
      images: [
        "bad-image.png",
        "mid-image.png",
        "good-image.png"
      ],
      width: 600,
      height: 600,
      fadeDuration: 500,
      disableCache: false
    });
  </script>
</body>
</html>
You can also import a dynamically generated image list using ES module syntax: 
<script type="module">
  import imageList from "./images/image_list.js";

  new ProgressiveImageLoader({
    container: document.getElementById("image-container"),
    images: imageList,
    width: 1250,
    fadeDuration: 0,
    disableCache: true
  });
</script>

​
Return Value

ProgressiveImageLoader does not return a meaningful value. The constructor kicks off the image-loading sequence as a side effect; you do not need to hold a reference to the returned instance.

​
Browser Compatibility

Because the library is written in pure vanilla JavaScript with no dependencies and no transpilation required, it runs in any modern browser that supports standard DOM APIs. No polyfills, bundlers, or framework integrations are needed — a plain <script> tag is all it takes.
The library does make use of ES module import syntax in the demo (for consuming image_list.js). If your project does not use modules, you can define the images array inline rather than importing it from an external file.

Build docs developers (and LLMs) love

Get started for freeTalk to us