Stable: 3.0.0
Canary: 3.0.1-alpha.1

Toggle Menu

Compare ×4000 file build

Eleventy 1.93s

Gatsby 29.05s

Image (Shortcodes)

Contents

Asynchronous Shortcode
- Configuration
- Template Usage
Advanced

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.

We can use the Image JavaScript API and wire it up to a Universal Shortcode.

Asynchronous Shortcode

Serve Cost 3

Build Cost 3

The examples below require an async-friendly shortcodes (works in Nunjucks, Liquid, JavaScript, and WebC).

Configuration

eleventy.config.js

ESM CommonJS

import Image from "@11ty/eleventy-img";

export default function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt, widths = [300, 600], sizes = "") {
		return Image(src, {
			widths,
			formats: ["avif", "jpeg"],
			returnType: "html",    // new in v6.0
			htmlOptions: {         // new in v6.0
				imgAttributes: {
					alt,               // required, though "" works fine
					sizes,             // required with more than one width, optional if single width output
					loading: "lazy",   // optional
					decoding: "async", // optional
				}
			}
		});
	});
};

const Image = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt, widths = [300, 600], sizes = "") {
		return Image(src, {
			widths,
			formats: ["avif", "jpeg"],
			returnType: "html",    // new in v6.0
			htmlOptions: {         // new in v6.0
				imgAttributes: {
					alt,               // required, though "" works fine
					sizes,             // required with more than one width, optional if single width output
					loading: "lazy",   // optional
					decoding: "async", // optional
				}
			}
		});
	});
};

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

More about Shortcodes

Read more about eleventyConfig.addShortcode and universal shortcodes. Use addAsyncShortcode in versions of Eleventy older than v2.0. You can also add these shortcodes to individual template engines, if you’d like!
Warning about Nunjucks Macros: Nunjucks macros cannot use async shortcodes. If you use macros, use the transform or synchronous shortcode methods.

Template Usage

Now you can use the image shortcode in your templates and the appropriate HTML will be generated for you (based on your specified Image options).

Liquid Nunjucks 11ty.js 11ty.cjs

{% image "cat.jpg", "photo of my tabby cat" %}
{% image "cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw" %}

The comma between arguments is optional in Liquid templates.

{% image "cat.jpg", "photo of my tabby cat" %}
{% image "cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw" %}

The comma between arguments is required in Nunjucks templates.

export default function() {
	let img1 = await this.image("cat.jpg", "photo of my tabby cat");
	let img2 = await this.image("cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw");

    return `${img1}

${img2}`;
};

module.exports = function() {
	let img1 = await this.image("cat.jpg", "photo of my tabby cat");
	let img2 = await this.image("cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw");

    return `${img1}

${img2}`;
};

If you want to use Eleventy Image in WebC, take note that it is possible to wire up the method below in WebC. However it is recommended to use the provided <eleventy-image> WebC component instead.

Advanced

Boost Performance: Optimize Images on Request

Serve Cost 1

Added in v3.0.0Added in Image v5.0.0The transformOnRequest feature is available for free with the Image HTML Transform and the Image WebC component.

Configuration

You can use transformOnRequest with Eleventy Shortcodes too with a little bit more configuration:

eleventy.config.js

ESM CommonJS

import Image from "@11ty/eleventy-img";
import { eleventyImageOnRequestDuringServePlugin } from "@11ty/eleventy-img";

export default function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt) {
		let html = await Image(src, {
			transformOnRequest: process.env.ELEVENTY_RUN_MODE === "serve",
			returnType: "html",
			htmlOptions: {
				imgAttributes: {
					alt, // required
				},
			}
		});

		return html;
	});

	// Add the dev server middleware manually
	eleventyConfig.addPlugin(eleventyImageOnRequestDuringServePlugin);
};

const Image = require("@11ty/eleventy-img");
const { eleventyImageOnRequestDuringServePlugin } = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt) {
		let html = await Image(src, {
			transformOnRequest: process.env.ELEVENTY_RUN_MODE === "serve",
			returnType: "html",
			htmlOptions: {
				imgAttributes: {
					alt, // required
				},
			}
		});

		return html;
	});

	// Add the dev server middleware manually
	eleventyConfig.addPlugin(eleventyImageOnRequestDuringServePlugin);
};

Using Shortcodes Alongside the Image HTML Transform Method

If you’re using an Image Shortcode or the WebC component in a project and you’re also adding the Image HTML Transform make sure you add eleventy:ignore to the <img> attributes so the images aren’t processed twice:

eleventy.config.js

ESM CommonJS

import Image from "@11ty/eleventy-img";

export default function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt) {
		let html = await Image(src, {
			returnType: "html",
			htmlOptions: {
				imgAttributes: {
					alt, // required
					"eleventy:ignore": ""
				}
			}
		});

		return html;
	});
};

const Image = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt) {
		let html = await Image(src, {
			returnType: "html",
			htmlOptions: {
				imgAttributes: {
					alt, // required
					"eleventy:ignore": ""
				}
			}
		});

		return html;
	});
};

Using `Image.generateHTML` to create markup

eleventy.config.js

ESM CommonJS

import Image from "@11ty/eleventy-img";

export default function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt) {
		let metadata = await Image(src, {
			widths: [600],
			formats: ["jpeg"],
		});

		return Image.generateHTML(metadata, {
			alt, // required
		});
	});
};

const Image = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt) {
		let metadata = await Image(src, {
			widths: [600],
			formats: ["jpeg"],
		});

		return Image.generateHTML(metadata, {
			alt, // required
		});
	});
};

Make your own markup

If you have an advanced use case and don’t want to use returnType: "html" or Image.generateHTML to create image markup, you can do it yourself!

Uses the entities npm package.

eleventy.config.js

ESM CommonJS

import { escapeAttribute } from "entities";
import Image from "@11ty/eleventy-img";

export default function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt) {
		if (alt === undefined) {
			// You bet we throw an error on missing alt (alt="" works okay)
			throw new Error(`Missing \`alt\` on myImage from: ${src}`);
		}

		let metadata = await Image(src, {
			widths: [600],
			formats: ["jpeg"],
		});

		let data = metadata.jpeg[metadata.jpeg.length - 1];
		return `<img src="${data.url}" width="${data.width}" height="${data.height}" alt="${escapeAttribute(alt)}" loading="lazy" decoding="async">`;
	});
};

const { escapeAttribute } = require("entities");
const Image = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
	eleventyConfig.addShortcode("image", async function (src, alt) {
		if (alt === undefined) {
			// You bet we throw an error on missing alt (alt="" works okay)
			throw new Error(`Missing \`alt\` on myImage from: ${src}`);
		}

		let metadata = await Image(src, {
			widths: [600],
			formats: ["jpeg"],
		});

		let data = metadata.jpeg[metadata.jpeg.length - 1];
		return `<img src="${data.url}" width="${data.width}" height="${data.height}" alt="${escapeAttribute(alt)}" loading="lazy" decoding="async">`;
	});
};

Synchronous Shortcode

Deprecated in Eleventy Image v4.0.0.

INFO:

The new Eleventy Transform is now preferred for situations that are not asynchronous-friendly (Handlebars, macros in Nunjucks, et al). For asynchronous-friendly templates (e.g. Nunjucks, Liquid, JavaScript), the Asynchronous Shortcode is another option. If you’re using WebC, use the provided WebC component.

Configuration

Use Image.statsSync to get the metadata of a source even if the image generation is not finished yet:

eleventy.config.js

ESM CommonJS

import Image from "@11ty/eleventy-img";

export default function (eleventyConfig) {
	eleventyConfig.addShortcode("myImage", function imageShortcode(src, cls, alt, widths = ["auto"], sizes = "100vh") {
		let options = {
			widths,
			formats: ["jpeg"],
		};

		// generate images: this is async but we don’t wait
		Image(src, options);

		let imageAttributes = {
			class: cls,
			alt,
			sizes,
			loading: "lazy",
			decoding: "async",
		};
		// get metadata even if the images are not fully generated yet
		let metadata = Image.statsSync(src, options);
		return Image.generateHTML(metadata, imageAttributes);
	});
};

const Image = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
	eleventyConfig.addShortcode("myImage", function imageShortcode(src, cls, alt, widths = ["auto"], sizes = "100vh") {
		let options = {
			widths,
			formats: ["jpeg"],
		};

		// generate images: this is async but we don’t wait
		Image(src, options);

		let imageAttributes = {
			class: cls,
			alt,
			sizes,
			loading: "lazy",
			decoding: "async",
		};
		// get metadata even if the images are not fully generated yet
		let metadata = Image.statsSync(src, options);
		return Image.generateHTML(metadata, imageAttributes);
	});
};

Image (Shortcodes)

Asynchronous Shortcode

Configuration

More about Shortcodes

Template Usage

Advanced

Boost Performance: Optimize Images on Request

Configuration

Using Shortcodes Alongside the Image HTML Transform Method

Using Image.generateHTML to create markup

Make your own markup

Synchronous Shortcode

Configuration

Using `Image.generateHTML` to create markup