When a user lands on a page containing a large, high-resolution image, they typically stare at a blank space or a spinner until the full file has finished downloading. Progressive image loading solves this by showing a recognisable — if blurry or pixelated — version of the image almost immediately, then seamlessly replacing it with successively sharper variants as each one arrives. The result is a page that feels fast and responsive even on slow connections, because users see something the moment the first lightweight file is ready.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.
What is ProgressiveImageLoader?
ProgressiveImageLoader is a zero-dependency, pure vanilla JavaScript library that automates the progressive-loading pattern for any image on your page. You supply an ordered array of image paths — from the lowest-quality variant to the full-resolution original — and the library handles everything else: sequential fetching, DOM management, and smooth CSS fade transitions between each quality step. There is nothing to install and nothing to configure beyond a single<script> tag. The entire API surface is one constructor call.
How it works
You provide an ordered image array
You give the constructor an
images array where index 0 is the most degraded
(smallest file, lowest fidelity) version and the last element is the full-quality
original. Any number of intermediate steps is supported.The library loads variants sequentially
Starting from index
0, ProgressiveImageLoader fetches each image in turn. As
soon as a file has loaded into the browser, it is displayed inside your container
element, replacing whatever was shown before.Smooth fade transitions
Each swap between quality levels is animated with a configurable CSS opacity fade,
controlled by the
fadeDuration option (in milliseconds). This prevents jarring
jumps and gives the progression a polished, intentional feel.The bandwidth trade-off
This trade-off is most favourable when the low-quality placeholder files are tiny (a few kilobytes), so the user gets visual feedback almost instantly, while the heavier high-quality file downloads in the background. The net experience feels faster even though more bytes are ultimately transferred.When to use ProgressiveImageLoader
Hero & banner images
Large above-the-fold images are the primary use case. Getting something visible
in under a second dramatically improves first impressions.
Photo galleries
Apply the loader to each gallery thumbnail or lightbox image to keep navigation
feeling snappy while full-resolution photos continue to load.
Slow or mobile connections
Users on throttled or cellular connections benefit the most — they see a usable
image quickly rather than waiting several seconds for a blank space to resolve.
Large data visualisations
High-resolution charts, maps, or diagrams exported as images can be shown in a
degraded form first, giving context before the detailed version arrives.
ProgressiveImageLoader works with any image format the browser supports — PNG, JPEG,
WebP, AVIF, and others. The companion Python tool image_ruiner.py (included in the
GitHub repository) can generate a full set of degraded PNG variants from any source
image automatically.
Next steps
Quickstart
Get a working progressive image on your page in under five minutes.
Configuration
Explore every constructor option — container, images, width, height, fadeDuration,
and disableCache.
Image Preparation
Learn how to use the bundled image_ruiner.py script to generate quality variants
from any source image.
Examples
See ProgressiveImageLoader in action with real-world patterns and a live demo.