---
title: 'Image shortcode'
description: 'The image shortcode: responsive <picture>, multiple formats, captions, and on-request transforms in dev. Built on @11ty/eleventy-img.'
slug: 'image-shortcode'
type: 'article'
date: 2026-04-28T00:00:00.000Z
lang: 'en'
url: 'https://www.eleventy-baseline.dev/docs/core-reference/image-shortcode/'
---

The shortcode is Baseline's; the underlying engine is `@11ty/eleventy-img`. The two halves split cleanly:

- **Baseline owns** the shortcode call signature ({% raw %}`{% image { src, alt, ... } %}`{% endraw %}), the default widths and format order, the filename convention, the on-request optimisation in dev, the `<picture>` and `<figure>` HTML assembly, and the cohabitation rule with `eleventyImageTransformPlugin`.
- **eleventy-img owns** the actual image transcoding, format conversion, content-hash digest, srcset emission, and remote-image fetching.

Anything you can configure on `@11ty/eleventy-img` directly, you can pass through the shortcode's options. Anything that is purely about the rendered HTML or the conventions Baseline applies on top is owned here.

---

## Usage

{% raw %}

```nunjucks
{% image {
	src: "/media/mountains.jpg",
	alt: "Mountains at sunset",
	caption: "Responsive image via baseline",
	widths: [320, 640, 960],
	formats: ["avif", "webp", "jpeg"]
} %}
```

{% endraw %}

---

### What it does

- Generates multiple formats and widths and returns a `<picture>` containing one `<source>` per format and a single `<img>` fallback. Wraps in `<figure>` when a caption is provided.
- Uses on-request transforms during `ELEVENTY_RUN_MODE=serve` (via eleventy-img's `transformOnRequest`) to keep dev startup quick. If that fails, retries without the flag and logs a warning. In build mode, errors throw immediately.
- Adds the `eleventy:ignore` attribute on `<img>` when `eleventyImageTransformPlugin` is registered, so the transform plugin doesn't reprocess the shortcode's output. Both can coexist in the same project; the shortcode owns explicit calls, the transform plugin owns content-level rewrites.

---

## The Image shortcode Shape

{% raw %}

```nunjucks
{% image {
	src: "/media/example.jpg",
	alt: "Description",
	caption: "",
	loading: "lazy",
	containerClass: "",
	imageClass: "",
	widths: [320, 640, 960, 1280, 1920, "auto"],
	sizes: "(max-width: 768px) 100vw, 768px",
	formats: ["avif", "webp"],
	outputDir: "./dist/media/",
	urlPath: "/media/",
	attrs: {},
	style: "",
	figure: true,
	setDimensions: true
} %}
```

{% endraw %}

Every key shown with its default. `src` and `alt` are required; the rest are optional.

---

### Required arguments

- `src` - local path or remote URL. Throws if missing. Local paths are resolved against `eleventyConfig.directories.input`.
- `alt` - required. A missing `alt` logs a warning but does not break the build. Use an empty string (`alt: ""`) for purely decorative images.

---

## Defaults

- **Widths**: `[320, 640, 960, 1280, 1920, 'auto']`
- **Formats**: `['avif', 'webp']` (order matters; the first format becomes the `<img>` fallback's source)
- **Sizes**: `'(max-width: 768px) 100vw, 768px'`
- **Output**: `urlPath: '/media/'`, `outputDir` derived from Eleventy's output directory (e.g. `./dist/media/`)
- **Filename**: `name-hash-widthw.format` (e.g. `hero-a1b2c3-640w.avif`). The hash is the first six characters of eleventy-img's content digest, so different sources sharing a basename do not collide.
- **Caption**: off unless `caption` is set; when set, wraps in `<figure>`.
- **Dimensions**: `width` and `height` are written onto `<img>` unless `setDimensions: false`.

---

### Common options

- `caption`, `loading` (`'lazy'` or `'eager'`), `containerClass`, `imageClass`
- `widths`, `formats`, `sizes`
- `outputDir`, `urlPath`
- `attrs` - extra attributes on `<img>`. The `class` key merges with `imageClass`; everything else passes through. `attrs.style` takes precedence over the top-level `style` argument.
- `style` - inline style on `<img>`. Convenience for the common case; use `attrs.style` if you also need to override.
- `figure` (default `true`) - only takes effect when `caption` is also set.
- `setDimensions` (default `true`) - set to `false` to omit `width`/`height` on the `<img>`.

---

## Notes

- Generated URLs are site-root-relative (`/media/...`). Keep `settings.url` set if you need absolute URLs for canonical tags or OpenGraph metadata; the shortcode itself does not prefix output paths with the site URL.
- If you also use `eleventyImageTransformPlugin`, the shortcode adds `eleventy:ignore` on its own `<img>` so the transform doesn't reprocess it. Use whichever fits the page: the shortcode for explicit calls with control over widths/formats, the transform for rewriting `<img>` tags written into Markdown.
- The dev-mode `transformOnRequest` retry is unguarded. If the second attempt also fails (bad src, missing file), the error surfaces. The warning blames `transformOnRequest` either way; the underlying cause may be elsewhere.

---

## See also

- [[site-settings | Site settings]] - `settings.url` for absolute URL contexts.
- [[plugin-entrypoint | Plugin entrypoint]] - `eleventyImageTransformPlugin` is opt-in.
- [[assets | Assets module]] - for static assets the shortcode does not own.