A JavaScript module to lazyload images in a responsive, lightweight way (with fallbacks for unsupported browsers).
ISC License
This package was inspired by https://github.com/ivopetkov/responsively-lazy/. It uses very similar markup, but significantly simplifies the way image replacement is handled under the hood. It also adds an optional fallback for when JavaScript is disabled.
Check out the examples for copy-pasteable code and more information about usage.
This example assumes webpack.
npm install --save responsive-lazyload
Load the module and initialize lazyloading in your app's script:
import responsiveLazyload from 'responsive-lazyload';
responsiveLazyload();
Include the following in the <head>
of your document.
<link rel="stylesheet"
href="node_modules/responsive-lazyload/dist/responsive-lazyload.min.css">
Place the lazyload markup anywhere in your app's markup:
<div class="js--lazyload">
<img alt="a lazyloaded image"
src="http://placekitten.com/400/300"
srcset="data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
data-lazyload="http://placekitten.com/400/300 1x,
http://placekitten.com/800/600 2x">
</div>
For more information and configuration options, see the examples.
NOTE: While unpkg is a fantastic tool, adding additional HTTP requests to your project will slow it down. For that reason, this approach is not recommended.
Just before the closing </body>
tag, add the lazyloading script:
<script src="https://unpkg.com/responsive-lazyload/dist/responsive-lazyload.umd.js" defer></script>
Include the following in the <head>
of your document:
<link rel="stylesheet"
href="https://unpkg.com/responsive-lazyload/dist/responsive-lazyload.min.css">
The initialization function is stored inside a global object called responsiveLazyload
. Initialize lazyloading by adding the following just below the script include:
<script>
responsiveLazyload();
</script>
Place the lazyload markup anywhere in your app's markup:
<div class="js--lazyload">
<img alt="a lazyloaded image"
src="http://placekitten.com/400/300"
srcset="data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
data-lazyload="http://placekitten.com/400/300 1x,
http://placekitten.com/800/600 2x">
</div>
For more information and configuration options, see the examples.
The markup to implement this is:
<div class="js--lazyload js--lazyload--loading">
<img alt="image description"
src="/images/[email protected]"
srcset="data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
data-lazyload="/images/image-300x150.jpg 300w,
/images/image-600x300.jpg 600w,
/images/image.jpg 690w,
/images/[email protected] 1380w">
</div>
responsiveLazyload()
.srcset
is a blank GIF, which avoids an unnecessary HTTP request.srcset
is added as data-lazyload
.The way responsiveLazyload()
works is to check if the image is inside the viewport, and — if so — swap out the srcset
for the data-lazyload
. This is much simpler than duplicating browser behavior to choose the optimal image size; instead, we just give the browser a srcset
and let it do its thing.
On browsers that don’t support srcset
, the regular src
attribute is used, so this should degrade gracefully.
To ensure that an image is still visible, even if JavaScript is disabled, add a <noscript>
block with the properly marked up image using srcset
without the lazyloading solution:
<div class="js--lazyload js--lazyload--loading">
<img alt="image description"
src="/images/[email protected]"
srcset="data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
data-lazyload="/images/image-300x150.jpg 300w,
/images/image-600x300.jpg 600w,
/images/image.jpg 690w,
/images/[email protected] 1380w">
<noscript>
<img alt="image description"
src="/images/[email protected]"
srcset="/images/image-300x150.jpg 300w,
/images/image-600x300.jpg 600w,
/images/image.jpg 690w,
/images/[email protected] 1380w">
</noscript>
</div>
To enable lazyloading, add the following to your initialization script:
import responsiveLazyload from 'responsive-lazyload';
responsiveLazyload({
containerClass: 'js--lazyload',
loadingClass: 'js--lazyload--loading',
callback: () => {},
});
option | default | description |
---|---|---|
containerClass |
js--lazyload |
Determines which elements are targeted for lazyloading. |
loadingClass |
js--lazyload--loading |
Applied to containers before loading. This is useful for adding loading animations. |
callback |
() => {} |
Fired on each image load. Useful for adding custom functionality after an image has loaded. |
To run this module locally for development, follow these steps:
# Clone the repo.
git clone [email protected]:jlengstorf/responsive-lazyload.js.git
# Move into the repo.
cd responsive-lazyload.js/
# Install dependencies.
npm install
# Run the build script.
npm run build
Tests are built using Jest. Run them with:
npm test
# Or, to remove all the extra crap npm spits out and only show test output:
npm test --silent