A simple Javascript library for progressive image loading
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo Create pil.css file Dec 22, 2015
LICENSE Initial commit Dec 22, 2015
README.md Update README.md May 4, 2018
pil.js Initial commit. Dec 22, 2015


This repo is no longer maintained. If you would like to take over ownership please get in touch.


A simple Javascript library for progressive image loading. Based on Medium's progressive image loading technique.


See the demo on CodePen

Note that the demo works best if you "Disable cache" in DevTools.


Include the script and CSS file:

<link rel="stylesheet" href="pil.css">
<script src="pil.js"></script>

Your images will need a wrapper with the pil class:

<figure class="pil">
    <img src="img/my-image.jpg" data-full-width="5616" data-full-height="3744" alt="">

You will also need to add data-full-width and data-full-height attributes to your images so the lib can calculate the aspect ratio.

Next you will need to create the thumbnail image that will be loaded before the main image is loaded. By default it will be loaded with a -thumb postfix. So for example if your image URL is img/my-image.jpg the thumb URL will be img/my-image-thumb.jpg, however this can be overridden by providing a URL in the data-pil-thumb-url attribute.

Thumbnail images should be no larger than 100px. Jpegs should be no more than 20% quality.

Finally you can initiate Pil by calling:



So you want to help out? That's awesome. Here is how you can do it:

If you are submitting a pull request please adhere to the existing coding standards used throughout the code and only submit 1 feature/fix per pull request. Pull requests containing multiple changes will be rejected.


Pil was created by Gilbert Pellegrom from Dev7studios. Released under the MIT license.