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.

ProgressiveImageLoader has zero dependencies and ships as a single JavaScript file, so getting started requires nothing more than downloading one file, dropping it next to your HTML, and writing a handful of lines of JavaScript. Follow the steps below to go from a blank page to a fully working progressive image loader.
ProgressiveImageLoader fires one HTTP request per image variant in your images array. If you provide three image paths, the browser will make three separate requests instead of one. Keep your low-quality variants small (a few kilobytes) so the placeholder appears near-instantly, making the extra requests worthwhile.
1

Download the library

Grab progressive-image-loader.js from the GitHub repository. Place it in the same directory as your HTML file, or in a js/ subfolder — wherever you prefer to keep your scripts.
your-project/
├── index.html
├── progressive-image-loader.js
└── images/
    ├── low-quality.png
    ├── medium-quality.png
    └── high-quality.png
2

Include the script in your HTML

Add a <script> tag that points to progressive-image-loader.js before your own script block. No module bundler, no npm install — just a plain script tag.
<script src="progressive-image-loader.js"></script>
Place this tag in the <body>, ideally just before your closing </body> tag so it does not block the initial HTML parse.
3

Add a container element

Create a <div> (or any block element) in your markup to act as the image container. Give it an id so you can reference it easily from JavaScript.
<div id="image-container"></div>
ProgressiveImageLoader injects and replaces <img> elements inside this container automatically — you do not need to add an <img> tag yourself.
4

Instantiate ProgressiveImageLoader

After the script tag, add your own <script> block and call the constructor. Pass in the container element and an images array ordered from least to most quality.
new ProgressiveImageLoader({
  container: document.getElementById("image-container"),
  images: [
    "images/low-quality.png",
    "images/medium-quality.png",
    "images/high-quality.png"
  ]
});
That’s the minimum required configuration. The library will immediately begin loading low-quality.png, display it, then load and fade in each subsequent variant until high-quality.png is shown.
5

(Optional) Customise with additional options

Fine-tune the experience using the optional constructor parameters:
OptionTypeDefaultDescription
widthnumber—Sets the rendered width of the image in pixels.
heightnumber—Sets the rendered height of the image in pixels.
fadeDurationnumber500Duration of the fade transition between quality levels, in ms.
disableCachebooleanfalseWhen true, appends a cache-busting query string to each URL.
new ProgressiveImageLoader({
  container: document.getElementById("image-container"),
  images: [
    "images/low-quality.png",
    "images/medium-quality.png",
    "images/high-quality.png"
  ],
  width: 600,
  height: 400,
  fadeDuration: 500,
  disableCache: false
});

​
Complete working example

Here is a full, self-contained HTML page you can copy, save as index.html, drop your image variants alongside it, and open directly in a browser. 
<!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>
  <div id="image-container"></div>

  <script src="progressive-image-loader.js"></script>
  <script>
    new ProgressiveImageLoader({
      container: document.getElementById("image-container"),
      images: [
        "low-quality.png",
        "medium-quality.png",
        "high-quality.png"
      ],
      width: 600,
      height: 400,
      fadeDuration: 500,
      disableCache: false
    });
  </script>
</body>
</html>
The browser will load low-quality.png first (the smallest file), display it immediately inside #image-container, then load and fade in medium-quality.png, and finally high-quality.png — giving the user a visible image as early as possible while the full-resolution version downloads in the background. You can see this pattern running live at the official demo page.
Don’t have degraded image variants yet? The repository includes a companion Python script called image_ruiner.py that takes any source image and generates a full sequence of progressively degraded PNG files. Run it once and you’ll have everything you need to populate your images array — no manual editing required.

Build docs developers (and LLMs) love

Get started for freeTalk to us