You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
hirusi 1cb6e9e736 fix: undefined import 5 months ago
example Remove unnecessary files 5 months ago
.editorconfig Initial version. 1 year ago
.eleventy.js fix: undefined import 5 months ago
.gitignore Remove unnecessary files 5 months ago
.npmignore Don't publish the examples to npm 8 months ago
.prettierrc Initial version. 1 year ago
LICENSE Update LICENSE 1 year ago
cache.js Update the plugin to use Sharp. 7 months ago
helpers.js refactor: remove redundant options 5 months ago
package-lock.json chore: update package version 5 months ago
package.json chore: update package version 5 months ago docs: remove removed options from readme 5 months ago

LazyImages plugin for 11ty

Banner image

What this plugin does:

  • 🔍 Finds IMG elements in your markup
  • Adds width and height attributes to the element
  • Defers loading the image until it is in/near the viewport (lazy loading)
  • 🖼️ Displays a blurry low-res placeholder until the image has loaded (LQIP)

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 Sharp; JPEG, PNG, WebP, TIFF, GIF, & SVG
  • Responsive images using srcset; the image in the src attribute will be used for determining the placeholder image and width/height attributes

v2 just released! View the release/upgrade notes

Like this project? Buy the original author a coffee via PayPal or ko-fi

Getting started

Install the plugin

In your project directory run:

# Using npm
npm install github:hirusi/eleventy-plugin-lazyimages --save-dev

# Or using yarn
yarn add github:hirusi/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) {

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, and some common questions are covered at the end of this file.

Configuration options

Key Type Description
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 file 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

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
  • Sharp - To read image metadata and generate low-res placeholders
  • LazySizes - Handles lazy loading


This project welcomes suggestions and Pull Requests!


  • Liam Fiddler - Initial work / maintainer - @liamfiddler
  • Ru Singh - stripped down to native lazy loading and removes LQIP

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


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


Common questions

Does my local image path have to match the output path?

(a.k.a Why do I have "Input file is missing" messages in my terminal?)

By default this plugin assumes the file referenced in a src attribute like <img src="/images/dog.jpg" /> exists at <project root>/images/dog.jpg or <project root>/src/images/dog.jpg.

If you prefer to store your images elsewhere the transformImgPath config option allows you to specify a function that points the plugin to your internal image path.

For example, if your file structure stores <img src="/images/dog.jpg" /> at <project root>/assets/dog.jpg you could set transformImgPath like:

// .eleventy.js
eleventyConfig.addPlugin(lazyImagesPlugin, {
  transformImgPath: (imgPath) => imgPath.replace('/images/', './assets/'),

(In the future we hope to make the plugin automatically manage these paths, once a fix for eleventy/issues/789 is completed)

Can I use a different lazy load script?

Yes! By default this plugin uses LazySizes to handle lazy loading, but any lazy load script that reads from the data-src attribute is supported via the scriptSrc configuration option.

We've included an example project in this repo demonstrating this plugin using vanilla-lazyload.

Note: if you need to modify the custom script's parameters the recommended approach is to set appendInitScript: false in this plugin's config. This tells the plugin to skip adding the script loader code to the page. It ignores any value set for scriptSrc and allows you to use your own method for including the custom script. The plugin will still set the data-src + width + height attributes on IMG tags and generate the low quality image placeholders, it just doesn't manage the actual lazy loading.

Can I use this plugin with a plugin that moves/renames image files?

Yes! The key to solving this problem is the order in which the plugins are defined in .eleventy.js. It is important this plugin runs after the plugin that moves/renames files otherwise this plugin may still be referencing the original filepath in the markup, not the one generated by the other plugin.

We've included an example project in this repo demonstrating this plugin with eleventy-plugin-local-images.

Upgrade notes


The underlying tool used to generate placeholders has switched from JIMP to Sharp. This allows the plugin to handle a greater variety of image formats, while also increasing in speed.

The API remains largely the same so most sites should not need to adjust their config.

  • The default values for maxPlaceholderWidth and maxPlaceholderHeight have been increased from 12 to 25 - this increases the quality of the LQIP without a significant change in filesize
  • placeholderQuality has been removed - at the size of the LQIP it didn't make much of a difference to filesize or image quality
  • The default value for preferNativeLazyLoad is now false - most users install this plugin to generate LQIP and the previous default meant the LQIP weren't visible in modern browsers

Like this project? Buy the original author a coffee via PayPal or ko-fi