Image (WebC)

Contents

Usage
- Configuration
- Template Usage

Eleventy Image Usage Types

Image HTML Transform: Recommended—start with this one! It’s the easiest to configure and is compatible with all template syntax.

Image Data Files: Use images to populate data in the Data Cascade.
Image JavaScript API: Low-level JavaScript API works independent of Eleventy.
Image Shortcodes: Use universal shortcodes in Nunjucks, Liquid, or 11ty.js templates.
Image WebC: Use a WebC component for WebC templates.

Usage

Serve Cost 1

Build Cost 3

Added in Image v3.1.0 Eleventy Image now provides a built-in <eleventy-image> WebC component for use in your Eleventy project.

Using Eleventy Image in WebC offers all the same great benefits you’re used to from Eleventy Image with an intuitive declarative HTML-only developer experience. WebC components work in *.webc files. For similar functionality in other template formats, use the the Liquid/Nunjucks/JavaScript shortcodes above (or even <eleventy-image> with the Render plugin).

Configuration

First, add the following to your project’s configuration file:

eleventy.config.js

ESM CommonJS

import eleventyWebcPlugin from "@11ty/eleventy-plugin-webc";
import { eleventyImagePlugin } from "@11ty/eleventy-img";

export default function (eleventyConfig) {
	// WebC
	eleventyConfig.addPlugin(eleventyWebcPlugin, {
		components: [
			// …
			// Add as a global WebC component
			"npm:@11ty/eleventy-img/*.webc",
		],
	});

	// Image plugin
	eleventyConfig.addPlugin(eleventyImagePlugin, {
		// Set global default options
		formats: ["webp", "jpeg"],
		urlPath: "/img/",

		// Notably `outputDir` is resolved automatically
		// to the project output directory

		defaultAttributes: {
			loading: "lazy",
			decoding: "async",
		},
	});
};

const eleventyWebcPlugin = require("@11ty/eleventy-plugin-webc");
const { eleventyImagePlugin } = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
	// WebC
	eleventyConfig.addPlugin(eleventyWebcPlugin, {
		components: [
			// …
			// Add as a global WebC component
			"npm:@11ty/eleventy-img/*.webc",
		],
	});

	// Image plugin
	eleventyConfig.addPlugin(eleventyImagePlugin, {
		// Set global default options
		formats: ["webp", "jpeg"],
		urlPath: "/img/",

		// Notably `outputDir` is resolved automatically
		// to the project output directory

		defaultAttributes: {
			loading: "lazy",
			decoding: "async",
		},
	});
};

Added in v3.0.0Added in Image v5.0.0During local development (when using --serve), <eleventy-image> images are not processed at build time and instead are optimized when requested in the browser. Read more about transformOnRequest.

HTML Tip: Read more about the special (and very useful) loading and decoding HTML attributes.

Now you can use the <eleventy-image> WebC component in your templates.

Template Usage

<img webc:is="eleventy-image" src="cat.jpg" alt="photo of my tabby cat">

<eleventy-image src="cat.jpg" alt="photo of my tabby cat"></eleventy-image>

<!-- Specify widths: -->
<img webc:is="eleventy-image" width="100, 200" src="cat.jpg" alt="photo of my tabby cat">
<img webc:is="eleventy-image" :width="[100, 200]" src="cat.jpg" alt="photo of my tabby cat">

<!-- Specify formats (overriding defaults set via the configuration) -->
<img webc:is="eleventy-image" formats="avif, png" src="cat.jpg" alt="photo of my tabby cat">
<img webc:is="eleventy-image" :formats="['avif', 'png']" src="cat.jpg" alt="photo of my tabby cat">

<!-- Change the url path or output dir (overriding defaults set via the configuration above) -->
<img webc:is="eleventy-image" url-path="/some-dir/" output-dir="_site/some-dir/" src="cat.jpg" alt="photo of my tabby cat">