Image (JavaScript API)

On this page

Usage
- Return object
- Return HTML

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

The JavaScript API here is the lowest-level use of Eleventy Image and returns a promise that resolves to a JavaScript object or an HTML string. This usage works independent of Eleventy.

my-node-script.js

ESM CommonJS

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

let src = "https://images.unsplash.com/photo-1608178398319-48f814d0750c";
let stats = await Image(src, {
	widths: [300],
});

console.log(stats);

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

// ESM is required for top level async/await.
(async () => {
	let src = "https://images.unsplash.com/photo-1608178398319-48f814d0750c";
	let stats = await Image(src, {
		widths: [300],
	});

	console.log(stats);
})();

Three things happen here:

(Optional) If the first argument is a full URL (not a local file path), we download the remote image and cache it locally using the Fetch plugin. This cached original is then used for the cache duration to avoid a bunch of network requests.
Images are then created for each format and width from the input source. In this example, two files are created: ./img/6dfd7ac6-300.webp and ./img/6dfd7ac6-300.jpeg.
The promise resolves with a metadata object describing those newly created optimized images.

Return object

The above JavaScript code will log a JavaScript object like this:

{
	webp: [
		{
			format: 'webp',
			width: 300,
			height: 300,
			filename: '6dfd7ac6-300.webp',
			outputPath: 'img/6dfd7ac6-300.webp',
			url: '/img/6dfd7ac6-300.webp',
			sourceType: 'image/webp',
			srcset: '/img/6dfd7ac6-300.webp 300w',
			size: 10184
		}
	],
	jpeg: [
		{
			format: 'jpeg',
			width: 300,
			height: 300,
			filename: '6dfd7ac6-300.jpeg',
			outputPath: 'img/6dfd7ac6-300.jpeg',
			url: '/img/6dfd7ac6-300.jpeg',
			sourceType: 'image/jpeg',
			srcset: '/img/6dfd7ac6-300.jpeg 300w',
			size: 15616
		}
	]
}

Return HTML

Use the returnType: "html" option to return HTML. Learn more about returnType and htmlOptions.

my-node-script.js

ESM CommonJS

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

let src = "https://images.unsplash.com/photo-1608178398319-48f814d0750c";
let html = await Image(src, {
	widths: [300],
	returnType: "html", // Added in v6.0
	htmlOptions: {
		imgAttributes: {
			alt: "", // required
		}
	}
});

console.log(html);

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

// ESM is required for top level async/await.
(async () => {
	let src = "https://images.unsplash.com/photo-1608178398319-48f814d0750c";
	let html = await Image(src, {
		widths: [300],
		returnType: "html", // Added in v6.0
		htmlOptions: {
			imgAttributes: {
				alt: "", // required
			}
		}
	});

	console.log(html);
})();

The above will log:

<picture><source type="image/webp" srcset="/img/yL0QoCVMHj-300.webp 300w"><img alt="" src="/img/yL0QoCVMHj-300.jpeg" width="300" height="300"></picture>