---
title: 'Image Transform'
description: 'Use Eleventy Image''s HTML transform to rewrite img tags into responsive picture markup with multiple formats, sizes, and caching, alongside Baseline.'
slug: 'image-transform'
type: 'article'
date: 2026-04-15T00:00:00.000Z
lang: 'en'
url: 'https://www.eleventy-baseline.dev/docs/how-to/image-transform/'
---

The image transform is eleventy-img's, not Baseline's. The two run side by side: `eleventyImageTransformPlugin` rewrites `<img>` and `<picture>` into responsive markup with generated assets and caching, and you add it to your config yourself.

{% alertBlock "info" %}

Baseline does not register this transform for you. You install and add it yourself.

{% endalertBlock %}

---

## Prerequisites

- Eleventy 3.x and `@11ty/eleventy-img` installed.
- `package.json` with `"type": "module"` and scripts (`start`, `build`).
- `settings.url` set to your origin (no subpath).
- Images referenced in your content or templates (local or remote).

---

## 1) Make sure `@11ty/eleventy-img` is present.

Baseline already requires it, but a fresh install never hurts:

```bash
npm install @11ty/eleventy-img
```

---

## 2) Enable the HTML transform in `eleventy.config.js`.

```js
import baseline, { config as baselineConfig } from '@apleasantview/eleventy-plugin-baseline';
import settings from './src/_data/settings.js';

import path from 'node:path';
import { eleventyImageTransformPlugin } from '@11ty/eleventy-img';

/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
export default async function (eleventyConfig) {
	await eleventyConfig.addPlugin(baseline(settings));

	eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
		urlPath: '/media/',
		outputDir: './dist/media/',
		formats: ['avif', 'webp', 'jpeg'],
		widths: [320, 640, 960, 1280],
		filenameFormat(id, src, width, format) {
			const extension = path.extname(src);
			const name = path.basename(src, extension);
			return `${name}-${id.slice(0, 6)}-${width}w.${format}`;
		}
	});
}

export const config = baselineConfig;
```

---

## 3) Write plain `<img>` in content.

The transform rewrites `<img>` into `<picture>` (with sources) at build time. Keep `alt` on every image. Example in Markdown:

```md
## A responsive image

<figure>
  <img src="/media/mountains.jpg" alt="Mountains at sunset" loading="lazy">
  <figcaption>
    Rendered responsively by the Eleventy Image Transform plugin.
  </figcaption>
</figure>
```

---

## 4) Handle remote images and caching.

Remote `src` values are fetched and cached on disk. Make sure the build environment can reach them. Cache defaults come from the plugin; adjust if you need a different cache directory.

---

## 5) Build and verify.

- Dev: `npm start`
- Build: `npm run build`
- Inspect rendered HTML: you should see `<picture>` with multiple `<source>` tags and `<img>` carrying width and height.
- Check generated files under `dist/media/`.

---

## Notes

- Keep `settings.url` origin-only; if you deploy under a subpath, set `pathPrefix` separately.
- `formats` order matters. The first format is preferred by the browser.
- Set `sizes` in the plugin options if you need custom responsive behaviour.
- For advanced options (cache, returnType, htmlOptions, remote fetch), see the [Eleventy Image docs](https://www.11ty.dev/docs/plugins/image/).
- When the transform plugin is loaded alongside Baseline's `image` shortcode, the shortcode adds `eleventy:ignore` to its output so the transform doesn't double-process it. No extra configuration needed.

---

## See also

- [[image-shortcode | Image shortcode reference]]