eleventy-plugin-img2picture
v5.0.1
Published
Eleventy plugin to replace <img> using <picture> with resized and optimized images.
Downloads
230
Maintainers
Readme
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+.
Table of Contents
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
| | 🚨 RequiredEleventy input directory. Should be same as Eleventy’s dir.input
. |
| imagesOutputDir | string
| | 🚨 RequiredOutput folder for optimized images. |
| urlPath | string
| | 🚨 RequiredURL 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
, andheight
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
.