@alexanderoff/eleventy-plugin-img2picture v2.1.1

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 12+

Features

• Drop-in plugin to replace all <img> in your website without shortcodes.
• Ignore image using data attribute.
• Download, cache, and optimize remote images.

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

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>

• class attribute on <img> will be moved to <picture>.
• 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"
/>

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>

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