Blurry Image Load
Synopsis
A lightweight, zero-dependency library that loads images on demand. Until the images are loaded, a very small version of each image is displayed with a blur filter over it. Inspired by Medium's progressive image loading of a similar style. Below is an example:
If the user's browser doesn't support CSS filters, a blank, gray shimmer is shown until the full-sized image loads. Below is an example:
Installation
Download the blurry-load.min.css and blurry-load.min.js files (found in the dist folder) and include them in your HTML:
<link rel="stylesheet" href="blurry-load.min.css" />
<script src="blurry-load.min.js"></script>
NOTE: If you do not want to see a flash of the tiny, pixelated image in browsers that do not support CSS filters, link to the JavaScript file in the head tag of your HTML.
Usage
In your JavaScript, create an instance of the BlurryImageLoad class:
const blurryImageLoad = new BlurryImageLoad();
The class has one method, load. If you want to call it once and load all of your images, add the class blurry-load to every <img> tag in your HTML (this includes img tags inside of picture elements). Then, the <img> tag must have two attributes: an src attribute that is the path to the image resized to be smaller, and a data-large attribute that is the path to the full-sized image. That implementation looks like this:
<img
class="blurry-load"
src="img/image-1-small.jpg"
data-large="img/image-1.jpg"
/>
blurryImageLoad.load();
Alternatively, the load function can be called by passing a comma-separated list or an array of the element(s) you would like to load:
blurryImageLoad.load(
document.querySelector(".img-1"),
document.querySelector(".img-2"),
document.querySelector(".img-3")
);
One possible implemention would be to pair this with the IntersectionObserver API to load each image as it comes into the viewport.
This library does NOT provide functionality for creating smaller versions of your images. That must be done on your own. For resizing images, I use Preview in macOS and change the width to 50px with the “Scale proportionally” option enabled. For help on how to use Preview to resize images, see this article. If you want to integrate resizing your images into your build workflow, you can use an image manipulation library like sharp or a Gulp plugin like gulp-image-resize.
"What about background images?"
Unfortunately, background images are not yet ready to take advantage of this library's functionality. In calling this library, images are applied a CSS filter to blur them. There is no way to apply the same kind of filter to a background image in CSS, however the back-drop filter draft shows hope that this could change in the future. At the time of writing this, its browser support is very small.
At the moment, my best recommendation is to make the background of your div the image's dominant color, then in your JavaScript, change the background to your image once the page has loaded. Below is a brief example of how to do this.
In your CSS:
.my-div {
background: #319ecb;
/* The dominant color of the image below */
}
.my-div-background-image {
background: url("img/background.jpg");
}
In your JavaScript:
window.onload = () => {
document.querySelector(".my-div").classList.add("my-div-background-image");
};
Browser Support
Tested to work in the latest version of Chrome, Firefox, Edge, and Safari. The only part of this library that has browser support that you should consider is ES2015 syntax (let/const, classes, etc.). If you want to support older browsers, you will have to transpile blurry-load.min.js yourself.
Otherwise, this library uses CSS filters, but this has a fallback in place. For browsers that don't support CSS filters, a blank gray div with a shimmer animation is shown before the full sized image is loaded (see the no-blur class in src/blurry-load.css for details).
Contributors
Dominic Brant.
Follow me on Twitter, and feel free to let me know if you have any thoughts/suggestions/problems.
License
MIT©
Fork this to your heart's content. :D
5 Nov 14, 2022
7.1k Jan 2, 2023
571 Dec 30, 2022
3 Nov 12, 2022
1.3k Dec 28, 2022
410 Dec 14, 2022
303 Dec 24, 2022
23 Nov 16, 2022
4 Jun 11, 2022
5 Jun 5, 2022
6 Aug 4, 2022
6 Oct 7, 2022
9 Aug 29, 2022
4 Aug 18, 2022
13 Oct 12, 2022
13 Jan 8, 2023
311 Nov 13, 2022
5.6k Dec 25, 2022
5 Sep 11, 2022