Responsive Images in WordPress 4.4

WordPress 4.4 will add native responsive image support by including srcset and sizes attributes to the image markup it generates. For background on this feature, read the merge proposal.

How it works

WordPress automatically creates several sizes of each image uploaded to the media library. By including the available sizes of an image into a srcset attribute, browsers can now choose to download the most appropriate size and ignore the others—potentially saving bandwidth and speeding up page load times in the process.

To help browsers select the best image from the source set list, we also include a default sizes attribute that is equivalent to (max-width: {{image-width}}px) 100vw, {{image-width}}px. While this default will work out of the box for a majority of sites, themes should customize the default sizes attribute as needed using the wp_calculate_image_sizes filter.

Note that for compatibility with existing markup, neither srcset nor sizes are added or modified if they already exist in content HTML.

For a full overview of how srcset and sizes works, I suggest reading Responsive Images in Practice, by Eric Portis over at A List Apart.

New functions and hooks

To implement this feature, we’ve added the following new functions to WordPress:

  • wp_get_attachment_image_srcset() – Retrieves the value for an image attachment’s srcset attribute.
  • wp_calculate_image_srcset() – A helper function to calculate the image sources to include in a srcset attribute.
  • wp_get_attachment_image_sizes() – Creates a sizes attribute value for an image.
  • wp_calculate_image_sizes() – A helper function to create the sizes attribute for an image.
  • wp_make_content_images_responsive() – Filters img elements in post content to add srcset and sizes attributes. For more information about the use of a display filter, read this post.
  • wp_image_add_srcset_and_sizes() – Adds srcset and sizes attributes to an existing img element. Used by wp_make_content_images_responsive().

As a safeguard against adding very large images to srcset attributes, we’ve included a max_srcset_image_width filter, which allows themes to set a maximum image width for images include in source set lists. The default value is 1600px.

A new default image size

A new default intermediate size, medium_large, has been added to better take advantage of responsive image support. The new size is 768px wide by default, with no height limit, and can be used like any other size available in WordPress. As it is a standard size, it will only be generated when new images are uploaded or sizes are regenerated with third party plugins.

The medium_large size is not included in the UI when selecting an image to insert in posts, nor are we including UI to change the image size from the media settings page. However, developers can modify the width of this new size using the update_option() function, similar to any other default image size.

Customizing responsive image markup

To modify the default srcset and sizes attributes,  you should use the wp_calculate_image_srcset and wp_calculate_image_sizes filters, respectively.

Overriding the srcset or sizes attributes for images not embedded in post content (e.g. post thumbnails, galleries, etc.), can be accomplished using the wp_get_attachment_image_attributes filter, similar to how other image attributes are modified.

Additionally, you can create your own custom markup patterns by using wp_get_attachment_image_srcset() directly in your templates. Here is an example of how you could use this function to build an <img> element with a custom sizes attribute:

$img_src = wp_get_attachment_image_url( $attachment_id, 'medium' );
$img_srcset = wp_get_attachment_image_srcset( $attachment_id, 'medium' );
<img src="<?php echo esc_url( $img_src ); ?>"
     srcset="<?php echo esc_attr( $img_srcset ); ?>"
     sizes="(max-width: 50em) 87vw, 680px" alt="A rad wolf">

Final notes

Users of the RICG Responsive Images Plugin should upgrade to version 3.0.0 now in order to be compatible with the functionality that included in WordPress 4.4.