# Lazy-load images (lazyload_images)

Defers offscreen image loading. How the mod_pagespeed lazyload_images filter works, when to use it, its risks and the Apache, nginx and IIS directives.

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

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

`lazyload_images` defers loading of images that are below the fold, reducing initial page weight and request count.

## How it works

In v1.15.0+r18 and later, on browsers that support it (the large majority), the filter adds the native `loading="lazy"` and `decoding="async"` attributes and leaves image URLs untouched. Images known to be above the fold are not deferred and instead get `fetchpriority="high"`. On older browsers — and in v1.15.0+r17 and earlier — the filter uses a JavaScript loader that loads images as the user scrolls them into view.

The `LazyloadImagesMode` directive controls this behavior: `auto` (the default) selects native or JavaScript per browser, `native` always uses the attributes, and `js` always uses the JavaScript loader (the behavior of v1.15.0+r17 and earlier).

When the filter has no data yet about which images are above the fold, it leaves the first images of the page alone so the largest visible image is not deferred. `LazyloadImagesSkipFirst` sets how many (default 1).

## When to use it

- Not in CoreFilters: it runs only when you enable it by name.
- Risk rating on these docs: **Generally safe**.
- Native mode (the default) is generally safe; test `js` mode first.

## Risks

- In `js` mode (or `auto` on older browsers), JavaScript-based lazy loading can interfere with image-dependent layout calculations, print rendering, and automated testing tools. The JavaScript mechanism also stands down on pages whose `Content-Security-Policy` disallows inline scripts; native mode is unaffected by CSP.

- Images that are immediately visible (above the fold) should not be lazy loaded. Above-fold detection is data-driven and imperfect; `LazyloadImagesSkipFirst` bounds the damage when no data is available, but pages with unusual layouts may still see a deferred visible image. Use `data-pagespeed-no-defer` on known-critical images.

## Configuration

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

**Apache**

```apache
ModPagespeedEnableFilters lazyload_images
```

**nginx**

```nginx
pagespeed EnableFilters lazyload_images;
```

**IIS (pagespeed.config)**

```text
pagespeed EnableFilters lazyload_images
```

Select the mechanism and tune the above-the-fold protection:

```apache
ModPagespeedLazyloadImagesMode auto
ModPagespeedLazyloadImagesSkipFirst 1
```

```nginx
pagespeed LazyloadImagesMode auto;
pagespeed LazyloadImagesSkipFirst 1;
```

To disable lazy loading for a specific image, add the [`data-pagespeed-no-defer`](https://modpagespeed.com/pagespeed-markers/#data-pagespeed-no-defer) attribute:

```html
<img src="hero.jpg" data-pagespeed-no-defer />
```

Images that already carry a `loading` attribute are always left untouched, so hand-tuned markup keeps working.

### On the worker

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

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

## Live example

See the before and after, with the source diff: [lazyload_images example](https://modpagespeed.com/examples/lazyload_images/).

## Frequently asked questions

**What does the lazyload_images filter do?**

`lazyload_images` defers loading of images that are below the fold, reducing initial page weight and request count.

**Is lazyload_images enabled by default?**

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

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

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

## Related filters

- [`inline_preview_images`](https://modpagespeed.com/docs/filters/inline_preview_images/): Inline preview images
- [`resize_images`](https://modpagespeed.com/docs/filters/resize_images/): Resize images
- [`prioritize_critical_images`](https://modpagespeed.com/docs/filters/prioritize_critical_images/): Prioritize critical images
- [`defer_iframe`](https://modpagespeed.com/docs/filters/defer_iframe/): Defer iframes
- [`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

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