`](#attributes-on-img)
- [Ignore Images](#ignore-images)
- [Specify widths on ``](#specify-widths-on-img)
- [Specify `class` for enclosing ``](#specify-class-for-enclosing-picture-tags-through-img)
- [Disk Cache](#disk-cache)
- [Example](#example)
- [FAQs](#faqs)
- [How to pick the right `sizes`?](#how-to-pick-the-right-sizes)
- [How is this plugin different from others?](#how-is-this-plugin-different-from-others)
## Features
- Drop-in plugin to replace all `` in your website without shortcodes.
- [Ignore image using data attribute](#ignore-images).
- Download, cache, and optimize [remote images](#remote-images).
- Skip processing unchanged and already existing images in the output directory. See [disk cache](#disk-cache).
## Supported Image Formats
This plugin uses [`eleventy-img`](https://www.11ty.dev/docs/plugins/image/) to optimize, and generate different sizes and formats of images. All [formats supported](https://www.11ty.dev/docs/plugins/image/#output-formats) by `eleventy-img` are supported by `eleventy-plugin-img2picture`.
## Usage
### Basic Usage
```js
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](#basic-usage). Just that, your Eleventy builds will be quite slow.
```js
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` | | 🚨 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
` element to enclosing `ℹ️ [What is SVG short circuiting?](https://www.zachleat.com/web/svg-short-circuit/) | | svgCompressionSize | `undefined \| "br"` | `undefined` | See [Eleventy Image Documentation](https://www.11ty.dev/docs/plugins/image/#skip-raster-formats-for-svg) | | filenameFormat | `function` | [`filenameFormatter()`](https://github.com/saneef/eleventy-plugin-img2picture/blob/b56ff9c3785700e68e37f2a1ed1a9ea12744ad73/lib/img2picture.js#L85) | Function used by [`eleventy-img`](https://www.11ty.dev/docs/plugins/image/) to generate image filenames. | | cacheOptions | `object` | `{}` | Cache options passed to [`eleventy-cache-assets`](https://www.11ty.dev/docs/plugins/cache/). | | sharpOptions | `object` | `{}` | Options passed to [Sharp constructor](https://sharp.pixelplumbing.com/api-constructor#parameters). | | 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](https://sharp.pixelplumbing.com/api-output#png). | | sharpJpegOptions | `object` | `{}` | Options passed to [Sharp image format converter for jpeg](https://sharp.pixelplumbing.com/api-output#jpeg). | | sharpAvifOptions | `object` | `{}` | Options passed to [Sharp image format converter for avif](https://sharp.pixelplumbing.com/api-output#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`](https://www.11ty.dev/docs/plugins/cache/#options) to change cache settings like, cache duration, and path. ### Attributes on `
`
- `sizes` will be hoisted on `` will be retained.
#### Ignore Images
Images with `data-img2picture-ignore="true"` or `data-img2picture-ignore` will be ignored by the plugin.
```html
```
#### Specify widths on ``
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 ``.
```html
```
#### Specify `class` for enclosing ``
You can provide class attribute for the enclosing `
```
### Disk Cache
Disk cache is a feature provided by the [`eleventy-img` plugin](https://www.11ty.dev/docs/plugins/image/). 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](https://github.com/11ty/demo-eleventy-img-netlify-cache) shows how to persist disk cache across Netlify builds.
### Example
```html
```
...will generate:
```html
` matching the file extensions. You can exclude `` using data attribute `data-img2picture-ignore`.