# Insert image dimensions (insert_image_dimensions)

Adds width and height attributes to img tags. The insert_image_dimensions filter: what it does, its risks and the Apache, nginx and IIS directives.

Canonical URL: https://modpagespeed.com/docs/filters/insert_image_dimensions/

- Category: Image
- CoreFilters: No
- OptimizeForBandwidth: No
- Risk: Generally safe

**`insert_image_dimensions`** adds explicit `width` and `height` attributes to `<img>` tags that lack them. This prevents layout shifts (CLS) but does not resize the image file itself. `insert_img_dimensions` is an accepted alternate spelling of the same filter.

## How it works

`insert_image_dimensions` declares the intrinsic size of each image: it adds `width` and `height` attributes carrying the pixel dimensions of the image file itself, read from the copy the module decoded, to `<img>` and image `<input>` elements that declare no dimensions at all: no `width` attribute, no `height` attribute, and no dimension inside a `style` attribute. An element that already declares any of those is left alone. The browser uses the pair to reserve the image's box before the file arrives, which is what removes the layout shift; the filter does not resize the image file and does not touch CSS sizing. It applies even to images the module decides not to optimize, as long as the file's dimensions could be decoded. It does not apply when image URLs are preserved (`ImagePreserveURLs`, as under OptimizeForBandwidth). Images that `inline_images` turns into `data:` URIs get no dimensions from this filter; `inline_images` instead removes `width` and `height` attributes that match the image's own size. Not a core filter; enable it by name.

## When to use it

- Not in CoreFilters: it runs only when you enable it by name.
- Risk rating on these docs: **Generally safe**.

## Risks

- `insert_image_dimensions` can break responsive layouts that rely on the absence of explicit dimensions. Test with your CSS.

## Configuration

Enable it in the module configuration, at server, virtual-host or location scope:

**Apache**

```apache
ModPagespeedEnableFilters insert_image_dimensions
```

**nginx**

```nginx
pagespeed EnableFilters insert_image_dimensions;
```

**IIS (pagespeed.config)**

```text
pagespeed EnableFilters insert_image_dimensions
```

| Parameter                     | Default | Description                                                               |
| ----------------------------- | ------- | ------------------------------------------------------------------------- |
| `ImageLimitResizeAreaPercent` | 100     | Only resize if the result is this percentage of the original area or less |

### On the worker

The worker runs its own pipeline, configured by flags. Its equivalent of this filter is the [image dimensions](https://modpagespeed.com/docs/worker-configuration/#image-dimensions) transform. Toggleable via [`--no-image-dimensions`](https://modpagespeed.com/docs/worker-configuration/#--no-image-dimensions).

Scoping, `ForbidFilters` and the thresholds filters read: [Choosing filters](https://modpagespeed.com/docs/filter-selection/).

## Frequently asked questions

**What does the insert_image_dimensions filter do?**

`insert_image_dimensions` adds explicit `width` and `height` attributes to `<img>` tags that lack them. This prevents layout shifts (CLS) but does not resize the image file itself. `insert_img_dimensions` is an accepted alternate spelling of the same filter.

**Is insert_image_dimensions enabled by default?**

No. `insert_image_dimensions` is not in CoreFilters, the default RewriteLevel; it runs only when you enable it by name with `EnableFilters`.

**How do I enable insert_image_dimensions on Apache and nginx?**

Add `ModPagespeedEnableFilters insert_image_dimensions` on Apache or `pagespeed EnableFilters insert_image_dimensions;` on nginx. On IIS, add `pagespeed EnableFilters insert_image_dimensions` to pagespeed.config.

## Related filters

- [`resize_images`](https://modpagespeed.com/docs/filters/resize_images/): Resize images
- [`resize_rendered_image_dimensions`](https://modpagespeed.com/docs/filters/resize_rendered_image_dimensions/): Resize to rendered dimensions
- [`convert_gif_to_png`](https://modpagespeed.com/docs/filters/convert_gif_to_png/): Convert GIF to PNG
- [`convert_jpeg_to_avif`](https://modpagespeed.com/docs/filters/convert_jpeg_to_avif/): Convert JPEG to AVIF
- [`convert_jpeg_to_progressive`](https://modpagespeed.com/docs/filters/convert_jpeg_to_progressive/): Progressive JPEG
- [`convert_jpeg_to_webp`](https://modpagespeed.com/docs/filters/convert_jpeg_to_webp/): Convert JPEG to WebP
- [`convert_png_to_jpeg`](https://modpagespeed.com/docs/filters/convert_png_to_jpeg/): Convert PNG to JPEG
- [`convert_to_avif_animated`](https://modpagespeed.com/docs/filters/convert_to_avif_animated/): Animated AVIF

This page is drawn from the [insert_image_dimensions entry on Image filters](https://modpagespeed.com/docs/image-filters/#insert_image_dimensions). Every filter in one table: [PageSpeed filters](https://modpagespeed.com/docs/filters/).