eleventy-plugin-img2picture

Eleventy plugin to replace <img> using <picture> with resized and optimized images.

This plugin is inspired by eleventy-plugin-local-respimg by Sam Richard.

Requires Node 14.15+.

Features
Supported Image Formats
Usage
FAQs
- How to pick the right sizes?
- How is this plugin different from others?

Features

Drop-in plugin to replace all <img> in your website without shortcodes.
Ignore image using data attribute.
Download, cache, and optimize remote images.
Skip processing unchanged and already existing images in the output directory. See disk cache.

Supported Image Formats

This plugin uses eleventy-img to optimize, and generate different sizes and formats of images. All formats supported by eleventy-img are supported by eleventy-plugin-img2picture.

Usage

Basic Usage

const img2picture = require("eleventy-plugin-img2picture");

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(img2picture, {
    // Should be same as Eleventy input folder set using `dir.input`.
    eleventyInputDir: ".",

    // Output folder for optimized images.
    imagesOutputDir: "_site",

    // URL prefix for images src URLS.
    // It should match with path suffix in `imagesOutputDir`.
    // Eg: imagesOutputDir with `_site/images` likely need urlPath as `/images/`
    urlPath: "",
  });
};

Recommended Usage

👋 It's recommended to use the plugin only on production builds (E.g.: $ ELEVENTY_ENV=production eleventy). The plugin works fine with basic usage. Just that, your Eleventy builds will be quite slow.

module.exports = function (eleventyConfig) {
  if (process.env.ELEVENTY_ENV === "production") {
    eleventyConfig.addPlugin(img2picture, {
      // Should be same as Eleventy input folder set using `dir.input`.
      eleventyInputDir: ".",

      // Output folder for optimized images.
      imagesOutputDir: "_site",

      // URL prefix for images src URLS.
      // It should match with path suffix in `imagesOutputDir`.
      // Eg: imagesOutputDir with `_site/images` likely need urlPath as `/images/`
      urlPath: "",
    });
  } else {
    // During development, copy the files to Eleventy's `dir.output`
    eleventyConfig.addPassthroughCopy("./images");
  }
};

Options

Name	Type	Default	Description
eleventyInputDir	`string`		🚨 Required Eleventy input directory. Should be same as Eleventy’s `dir.input`.
imagesOutputDir	`string`		🚨 Required Output folder for optimized images.
urlPath	`string`		🚨 Required URL prefix for images src URLS. It should match with path suffix in `imagesOutputDir`. Eg: imagesOutputDir with `_site/images` likely need urlPath as `/images/`
extensions	`array`	`["jpg", "png", "jpeg", "svg"]`	File extensions to optmize.
formats	`array`	`["avif", "webp", "svg", "jpeg"]`	Formats to be generated. ⚠️ The tags are ordered based on the order of formats in this array. Keep most compatible format at the end.
sizes	`string`	`"100vw"`	Default image `sizes` attribute
minWidth	`number`	`150`	Minimum image width to be generated
maxWidth	`number`	`1500`	Maximum image width to be generated
hoistImgClass	`boolean`	`false`	Move `class` attribute on `<img>` element to enclosing `<picture>` element.
pictureClass	`string`	`""`	Class attribute for the newly created `<picture>` elements
widthStep	`number`	`150`	Width increments between each generated image
fetchRemote	`boolean`	`false`	Fetch, cache, and optimize remote images.
dryRun	`boolean`	`false`	Don't generate image files. Only HTML tags are generated.
svgShortCircuit	`boolean \| "size"`	`"size"`	See Eleventy Image Documentation ℹ️ What is SVG short circuiting?
svgCompressionSize	`undefined \| "br"`	`undefined`	See Eleventy Image Documentation
filenameFormat	`function`	`filenameFormatter()`	Function used by `eleventy-img` to generate image filenames.
cacheOptions	`object`	`{}`	Cache options passed to `eleventy-cache-assets`.
sharpOptions	`object`	`{}`	Options passed to Sharp constructor.
sharpWebpOptions	`object`	`{}`	Options passed to [Sharp image format converter] for webp(https://sharp.pixelplumbing.com/api-output#webp).
sharpPngOptions	`object`	`{}`	Options passed to Sharp image format converter for png.
sharpJpegOptions	`object`	`{}`	Options passed to Sharp image format converter for jpeg.
sharpAvifOptions	`object`	`{}`	Options passed to Sharp image format converter for avif.

Remote images

Set fetchRemote: true in options to download, cache, and optimize remote images. fetchRemote is false by default. Use cacheOptions passed to eleventy-cache-assets to change cache settings like, cache duration, and path.

Attributes on `<img>`

sizes will be hoisted on <source> elements.
src, width, and height attributes will be replaced with corresponding values based on the optimized image.
All other attributes on <img> will be retained.

Ignore Images

Images with data-img2picture-ignore="true" or data-img2picture-ignore will be ignored by the plugin.

<img
  data-img2picture-ignore="true"
  src="/images/sunset-by-bruno-scramgnon.jpg"
  alt="Sunset"
/>

Specify widths on `<img>`

You can provide a comma separated list of widths using data-img2picture-widths. This will override default widths computed from config (minWidth, maxWidth, and widthStep) for a particular <img>.

<img
  data-img2picture-widths="200,400,600,800"
  src="/images/sunset-by-bruno-scramgnon.jpg"
  alt="Sunset"
/>

Specify `class` for enclosing `<picture>` tags through `<img>`

You can provide class attribute for the enclosing <picture> using data-img2picture-picture-class data attribute. This will override the class provided using pictureClass option.

<img
  data-img2picture-picture-class="w-full"
  src="/images/sunset-by-bruno-scramgnon.jpg"
  alt="Sunset"
/>

Disk Cache

Disk cache is a feature provided by the eleventy-img plugin. This plugin will skip unchanged, and already existing images in the output path. If you don't delete generated image between builds, you'll get faster builds. This sample project shows how to persist disk cache across Netlify builds.

Example

<img
  class="w-full"
  src="shapes.png"
  alt="Shapes"
  data-variant="bleed"
  loading="eager"
  decoding="auto"
/>

...will generate:

<picture class="w-full"
  ><source
    type="image/avif"
    srcset="
      shapes-150w.avif   150w,
      shapes-300w.avif   300w,
      shapes-450w.avif   450w,
      shapes-600w.avif   600w,
      shapes-750w.avif   750w,
      shapes-900w.avif   900w,
      shapes-1050w.avif 1050w,
      shapes-1200w.avif 1200w,
      shapes-1350w.avif 1350w
    "
    sizes="100vw" />
  <source
    type="image/webp"
    srcset="
      shapes-150w.webp   150w,
      shapes-300w.webp   300w,
      shapes-450w.webp   450w,
      shapes-600w.webp   600w,
      shapes-750w.webp   750w,
      shapes-900w.webp   900w,
      shapes-1050w.webp 1050w,
      shapes-1200w.webp 1200w,
      shapes-1350w.webp 1350w
    "
    sizes="100vw" />
  <source
    type="image/jpeg"
    srcset="
      shapes-150w.jpeg   150w,
      shapes-300w.jpeg   300w,
      shapes-450w.jpeg   450w,
      shapes-600w.jpeg   600w,
      shapes-750w.jpeg   750w,
      shapes-900w.jpeg   900w,
      shapes-1050w.jpeg 1050w,
      shapes-1200w.jpeg 1200w,
      shapes-1350w.jpeg 1350w
    "
    sizes="100vw" />
  <img
    src="shapes-150w.jpeg"
    width="1350"
    height="1350"
    alt="Shapes"
    data-variant="bleed"
    sizes="100vw"
    loading="eager"
    decoding="auto"
/></picture>

FAQs

How to pick the right `sizes`?

I highly recommend to use the magical respimagelint - Linter for Responsive Images by Martin Auswöger.

How is this plugin different from others?

Plugins like eleventy-plugin-respimg, and eleventy-plugin-images-responsiver utilizes shortcodes or attributes to optimize images. The eleventy-plugin-img2picture doesn't rely on shortcode. It optimizes all <img> matching the file extensions. You can exclude <img> using data attribute data-img2picture-ignore.