Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including eleventy-plugin-lazyimages with all npm packages installed. Try it out:

var eleventyPluginLazyimages = require("eleventy-plugin-lazyimages")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

eleventy-plugin-lazyimages v1.1.1

An 11ty plugin that adds lazy loading to your images

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) {

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

maxPlaceholderWidthIntegerThe maximum width in pixels of the generated placeholder image. Recommended values are between 6 and 15.
Default: 12
maxPlaceholderHeightIntegerThe maximum height in pixels of the generated placeholder image. Recommended values are between 6 and 15.
Default: 12
placeholderQualityIntegerThe JPEG compression quality of the generated placeholder image.
Default: 60
imgSelectorStringThe DOM selector used to find IMG elements in the markup.
Default: img
transformImgPathFunctionA function that takes the IMG src attribute and returns a string representing the actual path to your image.
cacheFileStringCache 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
appendInitScriptBooleanAppends 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
scriptSrcStringThe URI for the lazy load script that is injected into the markup via appendInitScript.
preferNativeLazyLoadBooleanUse 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
classNameArrayThe 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


This project welcomes suggestions and Pull Requests!


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


RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free