LazyImages plugin for 11ty

🔍 Finds IMG elements in your markup

💉 Injects the source image width and height attributes to the element

🔜 Defers loading of the image until it is in/near the viewport (lazy loading)

🖼️ Displays a blurry low-res placeholder until the image has loaded

This plugin supports:

Any 11ty template format that outputs to a .html file
Absolute and relative image paths
Custom image selectors; target all images or only images in a certain part of the page
Placeholder generation for all image formats supported by JIMP; BMP, GIF, JPEG, PNG, & TIFF
Responsive images using srcset; the image in the src attribute will be used for determining the placeholder image and width/height attributes

Getting started

Install the plugin

In your project directory run:

# Using npm
npm install eleventy-plugin-lazyimages --save-dev

# Or using yarn
yarn add eleventy-plugin-lazyimages --dev

Then update your project's .eleventy.js to include the plugin:

const lazyImagesPlugin = require('eleventy-plugin-lazyimages');

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(lazyImagesPlugin);
};

Tweak your CSS (optional)

This plugin will automatically set the width and height attributes for each image based on the source image dimensions. You might want to overwrite this with the following CSS:

img {
  display: block;
  width: 100%;
  max-width: 100%;
  height: auto;
}

The above CSS will ensure the image is never wider than its container and the aspect ratio is maintained.

Configure the plugin (optional)

You can pass an object with configuration options as the second parameter:

eleventyConfig.addPlugin(lazyImagesPlugin, {
  imgSelector: '.post-content img', // custom image selector
  cacheFile: '', // don't cache results to a file
});

A full list of available configuration options are listed below.

Configuration options

Key	Type	Description
`maxPlaceholderWidth`	Integer	The maximum width in pixels of the generated placeholder image. Recommended values are between 6 and 15. Default: `12`
`maxPlaceholderHeight`	Integer	The maximum height in pixels of the generated placeholder image. Recommended values are between 6 and 15. Default: `12`
`placeholderQuality`	Integer	The JPEG compression quality of the generated placeholder image. Default: `60`
`imgSelector`	String	The DOM selector used to find IMG elements in the markup. Default: `img`
`transformImgPath`	Function	A function that takes the IMG `src` attribute and returns a string representing the actual path to your image.
`cacheFile`	String	Cache image metadata and placeholder images to this filename. Greatly speeds up subsequent builds. Pass an empty string to turn off the cache. Default: `.lazyimages.json`
`appendInitScript`	Boolean	Appends code to initialise lazy loading of images to the generated markup. Set this to `false` if you include your own lazy load script. Default: `true`
`scriptSrc`	String	The URI for the lazy load script that is injected into the markup via `appendInitScript`. Default: `https://cdn.jsdelivr.net/npm/lazysizes@5/lazysizes.min.js`
`preferNativeLazyLoad`	Boolean	Use the native browser `loading="lazy"` instead of the lazy load script (if available). Set this to `false` if you always want to use the lazy load script. Default: `true`
`className`	Array	The class names added to found IMG elements. Do not change this value unless you intend to use your own `scriptSrc`. Default: `['lazyload']`

Example projects

Example projects using the plugin can be found in the /example directory.

Basic - using default configuration
Custom selector - using a custom image selector to only target image in certain DIVs
Usage with eleventy-plugin-local-images - using this plugin with eleventy-plugin-local-images

Built with

JSDOM - To find and modify image elements in 11ty's generated markup
JIMP - To read image metadata and generate low-res placeholders
LazySizes - Handles lazy loading

Contributing

This project welcomes suggestions and Pull Requests!

Authors

Liam Fiddler - Initial work - @liamfiddler

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments

The wonderfully supportive team at Mentally Friendly
Everyone who has contributed to the 11ty project, without whom this plugin wouldn't run
José M. Pérez's blog post about progressive image loading which served as the inspiration for this plugin
Addy Osmani's blog post about lazy loading which served as the inspiration for the init script

evheniy / eleventy-plugin-lazyimages