/eleventy-plugin-lazyimages

An 11ty plugin that adds lazy loading to your images

Primary LanguageJavaScriptMIT LicenseMIT

LazyImages plugin for 11ty

Banner image

🔍 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.

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

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