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.

Every ProgressiveImageLoader instance is configured through a single options object passed to the constructor. Two options are required — container and images — while the remaining four are optional with sensible defaults baked into the library. Understanding each option lets you tune both the visual behaviour and network characteristics to match your use case.

​
Constructor signature

new ProgressiveImageLoader({
  container,     // required
  images,        // required
  width,         // optional, default: 600
  height,        // optional, default: 600
  fadeDuration,  // optional, default: 500
  disableCache   // optional, default: false
});

​
Options reference

​
container
HTMLElement
required
The DOM element that will contain the progressive image. Pass a direct reference to the element — for example document.getElementById('image-container'). The loader appends a positioned wrapper <div> with two stacked <img> elements inside this container.The container does not need any special CSS; the loader sets all required positioning styles on the inner wrapper automatically.
​
images
string[]
required
An array of image path strings ordered from least quality to most quality. The loader requests each image in array order and replaces the displayed image whenever a higher-index (better) image finishes loading.Place your most-degraded (blurriest / lowest-resolution) image at index 0 and your full-quality image last. At least two images are recommended; a single-entry array defeats the purpose of progressive loading.
images: [
  "images/degraded_100.png",  // worst quality — shown first
  "images/degraded_050.png",  // medium quality
  "images/degraded_000.png",  // full quality — shown last
]
​
width
number
default:"600"
Display width of the image in pixels. The loader sets this as the width CSS value on the inner wrapper element. Both stacked <img> elements stretch to fill this wrapper using width: 100%.If you omit this option, the image is displayed at 600 px wide regardless of the source image’s natural dimensions.
​
height
number
default:"600"
Display height of the image in pixels. Works identically to width — applied as a CSS height on the inner wrapper. Images are fitted inside the box using object-fit: contain, so your original aspect ratio is always preserved without cropping.If you omit this option, the wrapper defaults to 600 px tall. When combined with object-fit: contain, a mismatched aspect ratio will simply leave empty space on two sides rather than distorting the image.
​
fadeDuration
number
default:"500"
Duration of the cross-fade transition between quality levels, in milliseconds. The library applies this value as the transition duration on each <img> element’s opacity property.Higher values produce a slower, more visible blend; 0 makes each quality upgrade appear instantaneously.
​
disableCache
boolean
default:"false"
When true, appends a timestamp query parameter (?t=<unix-ms>) to every image URL before fetching. This forces the browser to bypass its HTTP cache and always download a fresh copy of each image.Set this to true during active development when you are frequently regenerating test images and need to guarantee the latest version is displayed.

​
Full configuration example

The snippet below mirrors the structure used in the official README and shows every option in one place. 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My Page</title>
</head>
<body>
  <div id="image-container"></div>

  <script src="progressive-image-loader.js"></script>
  <script>
    new ProgressiveImageLoader({
      container:    document.getElementById("image-container"),
      images: [
        "bad-image.png",   // least quality — loaded first
        "mid-image.png",
        "good-image.png",  // most quality — loaded last
      ],
      width:         600,   // display width in px
      height:        600,   // display height in px
      fadeDuration:  500,   // 500 ms cross-fade
      disableCache:  false  // allow browser caching
    });
  </script>
</body>
</html>
Set fadeDuration: 0 when testing locally so quality upgrades snap in immediately, making it easy to verify each image in the sequence is loading correctly without waiting for transitions to finish.
Enabling disableCache: true means the browser downloads every image in the images array fresh on every page load, regardless of whether a cached version is available. For a 9-image sequence this can multiply your bandwidth use significantly — keep it set to false (the default) in production.
Progressive loading itself increases total network requests compared to loading a single image. A sequence of 3 images means the browser makes 3 separate HTTP requests. Keep your image array reasonably sized and ensure your lower-quality images are genuinely small files so the first visible frame arrives quickly.

Build docs developers (and LLMs) love

Get started for freeTalk to us