Responsive Images

Note: New filter as of 1.10.33.0

Configuration

The 'Responsive Images' filter requires the 'Resize Images' filter; these filters are enabled by specifying:

Apache:

ModPagespeedEnableFilters responsive_images,resize_images

Nginx:

pagespeed EnableFilters responsive_images,resize_images;

in the configuration file. An additional zoom feature can be enabled by specifying:

Apache:

ModPagespeedEnableFilters responsive_images_zoom

Nginx:

pagespeed EnableFilters responsive_images_zoom;

The 'Responsive Images' filter won't optimize an image if it has the data-pagespeed-no-transform or pagespeed_no_transform attribute. Usage:

  <img src="example.png" data-pagespeed-no-transform>

Description

This filter makes images responsive by adding srcset attributes which provide multiple versions for different pixel density screens.

If responsive_images_zoom is enabled, it also extends the default srcset functionality by loading higher resolution images when the user zooms in.

In order to take advantage of this filter, the original image must explicitly specify height and width attributes and src must be a high enough resolution image (at least 2x larger than these height and width values).

Example

For example, if the original HTML looks like this:

<img src="foo.png" width="100" height="100">

and foo.png is 1000x1000, then PageSpeed will rewrite it into:

<img src="100x100xfoo.png.pagespeed.ic.HASH1.png" width="100" height="100"
     srcset="150x150xfoo.png.pagespeed.ic.HASH2.png 1.5x,200x200xfoo.png.pagespeed.ic.HASH3.png 2x,300x300xfoo.png.pagespeed.ic.HASH4.png 3x, foo.png 10x">

Which will load the normal 100x100 image on standard displays, higher-resolution 150x150, 200x200 or 300x300 image on 1.5x, 2x, or 3x displays, or the full original 1000x1000 image when users zoom in enough.

If foo.png is 200x200, no 3x or higher version will be added to srcset. If foo.png is only 100x100, no srcset will be added at all.

Online Example

You can see the filter in action at www.modpagespeed.com.

Limitations

• Before 1.12.34.1, PageSpeed would not optimize images referenced in existing srcset attributes.
• Images must have explicit height and width attributes and src must refer to a higher resolution image.
• PageSpeed does not mix inline images with srcsets. If the largest size image is inlinable, we just inline that. Otherwise we do not inline any of the images and use a srcset instead.
• The Responsive Images filter is not compatible with the Local Storage Cache filter. Images modified by the Responsive Images filter will not be stored in Local Storage.
• PageSpeed's default memory limits keep it from processing images larger than 8 million pixels (8MP). If you have images larger than this, it won't be able to resize them to generate the lower resolution versions. See ImageResolutionLimitBytes for more details on increasing this limit or resizing source images to be under the limit.

Risks

This filter will increase cache usage by 4x for all images which have explicit width and height attributes. (This is true even if the original image is only 1x.) If this pushes your cache over the FileCacheSize, then you may experience cache churn which makes PageSpeed much less effective.

This filter has the same risks inherent in the 'Resize Images' filter. See Optimize Images - Risks for more information.

This filter adds a srcset attribute to images. This will break any JavaScript which changes images by modifying their src attribute. On high-density displays, modifying the src attribute will not actually change the image. As a work-around, you can add a data-pagespeed-no-transform attribute to any <img> tag to prevent PageSpeed from adding a srcset.

If using responsive_images_zoom, the JavaScript used to implement that feature may conflict with other JS on the page.