Inline Preview Images

Configuration

The 'Inline Preview Images' filter is enabled by specifying:

Apache:

ModPagespeedEnableFilters inline_preview_images

Nginx:

pagespeed EnableFilters inline_preview_images;

in the configuration file.

The 'Resize Mobile Images' filter is enabled by specifying:

Apache:

ModPagespeedEnableFilters resize_mobile_images

Nginx:

pagespeed EnableFilters resize_mobile_images;

in the configuration file.

Description

The 'Inline Preview Images' filter generates low quality versions of the images that are inlined in the HTML page. Users experience faster rendering of the page and the low quality images are replaced by high quality versions after an onload event is triggered. The filter works on images found in <img> tags.

The 'Resize Mobile Images' filter works like Inline Preview Images, but is applied only for mobile browsers, and shrinks the size in pixels of the placeholder images on mobile devices to better fit the device screen size. If Inline Preview Images is activated and Resize Mobile Images is not, full-resolution preview images will be served to both desktop and mobile browsers.

Note: inline_preview_images and resize_mobile_images should be used together with insert_image_dimensions to avoid reflow as the images load.

Operation

The 'Inline Preview Images' filter changes the src attribute of <img> elements to data-pagespeed-high-res-src based on a few parameters which are described in next section. It generates low quality versions of the images and replaces the src attribute with these. The low quality images are replaced by high quality versions after an onload event is triggered.

Parameters that affect optimization

Apache:

ModPagespeedMaxInlinedPreviewImagesIndex IndexNumber

Nginx:

pagespeed MaxInlinedPreviewImagesIndex IndexNumber;

The first IndexNumber images on the page are replaced by low quality images. Negative numbers will result in all images being rewritten. Zero means no image will be rewritten. The default value of this parameter is -1. Refer to the Risks section for trade offs on setting this value.

Apache:

ModPagespeedMinImageSizeLowResolutionBytes MinBytes

Nginx:

pagespeed MinImageSizeLowResolutionBytes MinBytes;

MinBytes, a positive integer, is the minimum size in bytes of any image for which a low quality image is generated. No images will be rewritten for zero and negative values.

'Inline Preview Images' injects JavaScript that uses a beacon to report back to the server the images that are visible in the client's initial viewport (above the fold). It takes a few accesses of a page for the data to be reported back and processed but eventually the above-the-fold images will be known and will be replaced with low quality versions while all others will be handled normally; until then images are replaced as described above.

The use of beacons can be disabled using the ModPagespeedCriticalImagesBeaconEnabled directive. If they are disabled, 'Inline Preview Images' will not inject the JavaScript and images will be replaced with low quality versions as described above.

Example

You can see the Inline Preview Images filter in action at www.modpagespeed.com on this example. You can also see this example of the Resize Mobile Images filter.

Risks

This filter is considered moderately risky. The main risk is that the HTML becomes bloated due to the embedded low quality image data. MaxInlinedPreviewImagesIndex should be chosen appropriately; otherwise, if images below the fold are inlined, there is no user perceivable gain, but the page takes longer to load due to the extra bytes in the HTML.

Note that MaxInlinedPreviewImagesIndex and MinImageSizeLowResolutionBytes should not be used to disable inlining of preview images (for example by setting either parameter to 0). Instead, the inline_preview_images and resize_mobile_images filters themselves should be disabled.