Common APIs – responsive images

This tutorial will focus on the Responsive Images API, including a brief history of responsive images in WordPress, how the API works, and how it can be used for theme development.

Learning outcomes

1. Explain what responsive images are and how they work
2. Describe how the WordPress Responsive Images API works when adding images from the media library
3. Customize the responsive image markup

Comprehension questions

1. How are responsive images different from regular images?
2. What are the two image tag properties that are set for responsive images?
3. Why are responsive images better than other solutions?

Introduction

Hey there, and welcome to Learn WordPress.

In this tutorial, you’re going to learn about the WordPress Responsive Images API.

You will learn what responsive images are and why you should use them, how the WordPress Responsive Images API works, and how to customize the responsive images markup if you need to.

What are responsive images?

Responsive images are images that can adapt to the screen size of the device they are being viewed on. This is important because it means that the image will always look good, no matter what device it is being viewed on.

Let’s take a look at an example.

Most modern browsers have a special mode for viewing web page layouts on mobile devices. In Chrome-based browsers it’s called Device Mode and in Firefox and Safari, it’s called Responsive Design Mode. You can usually access this from the browser’s developer tools. Once you enable this mode, you can see what a web page looks like on different devices.

If you look at the header image in this example, you can see that it gets cropped when you view it on a mobile device. However, the image in the content area does not, it merely shows the image at a smaller size.

So what you might want is to be able to show a cropped version of that image on mobile devices, and the full image on desktop devices. This is where responsive images come in.

As you can see in this responsive images example, both the header image and the main content image are cropped when you switch to mobile.

While the knowledge of how responsive images works is outside the scope of this tutorial, you can read more about how to implement responsive images in the MDN Web Docs.

The WordPress Responsive Images API

Since WordPress 4.4, responsive images is supported natively in WordPress by including srcset and sizes attributes to the image markup generated by the wp_get_attachment_image() function. This means that it’s on by default, and any images WordPress generates will automatically be responsive.

To understand how it works, let’s look at a simple example.

To start, add an image to the media library in your WordPress site.

If you then browse to the uploads directory and take a look at where the image is stored, you will see that there are multiple versions of the image.

This is because WordPress automatically generates multiple versions of the image in different sizes, which can then be used in different contexts.

Before responsive images, developers would attempt to dynamically serve different images to browsers based on the device type. The server would check what device size is being used, and then serve the appropriate image.

This would have been possible by using the User Agent string, which is a string that is sent by the browser to the server, and contains information about the browser and device being used.

// check the $_SERVER["HTTP_USER_AGENT"] variable to see if this is a mobile device request
$isMob = is_numeric(strpos(strtolower($_SERVER["HTTP_USER_AGENT"]), "mobile")); 

if($isMob){ 
    echo 'Using Mobile Device...'; 
}else{ 
    echo 'Using Desktop...'; 
}

However, this makes testing difficult, as you need to either test on physical devices, use a service like BrowserStack, or set up the user agent string in your testing environment.

Responsive design uses things like media queries to allow a single page to be rendered that will respond in the browser based on things like viewport width and display density. Responsive images follows this strategy and sends all of the information to the browser up front and let’s the browser take care of loading the appropriate image rather than making those decisions on the server before the page is loaded.

Let’s see this in action by adding your image to a post, and setting it’s size to full size in the editor.

When you preview the image, you’ll see that the image tag contains more than just the image URL. It also contains a srcset attribute and a sizes attribute.

<img decoding="async" fetchpriority="high" width="799" height="533" src="https://learnpress.test/wp-content/uploads/2023/09/water-4.jpeg" alt="" class="wp-image-9" 
     srcset="
     https://learnpress.test/wp-content/uploads/2023/09/water-4.jpeg 799w, 
     https://learnpress.test/wp-content/uploads/2023/09/water-4-300x200.jpeg 300w, 
     https://learnpress.test/wp-content/uploads/2023/09/water-4-768x512.jpeg 768w" 
     sizes="(max-width: 799px) 100vw, 799px">

Let’s take a closer look at this image tag to understand what those attributes do.

The srcset attribute contains a list of all the different versions of the image that WordPress has generated, along with that image’s width in pixels.

In this case, there are 3 different versions of the image, with widths of 799, 769, and 300 respectively.

The sizes attribute specifies the layout width of the image for each of a list of media conditions. In this example the media condition is (max-width: 799px), and there are two layout widths, 100vw and 799px. 100vw means that the image will be displayed at 100% of the viewport width, and 799px means that the image will be displayed at 799px.

So in this example, the image will be displayed at 100% of the viewport width if the width of the viewport is less than 799px, otherwise it will display the image at a width of 799px.

The browser can then use this information to determine which image to load based on the device it is being viewed on determined by its viewport width. No more server-side logic is required, thereby speeding up page request times. And because the images are served statically, they can be cached by the browser, further speeding up page load times.

New functions and hooks

WordPress 4.4 introduced a number of new functions and hooks to make it easier to work with responsive images.

• 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_image_add_srcset_and_sizes() – Adds srcset and sizes attributes to an existing img element.

As a safeguard against adding very large images to srcset attributes, a max_srcset_image_width filter has been added, which allows themes to set a maximum image width for images included in srcset lists. The default value is 2048px.

Customizing the responsive images markup

It is also possible to customize the responsive images markup if you need to.

You can modify the default srcset and sizes attributes, by using the wp_calculate_image_srcset filter and the wp_calculate_image_sizes filter or override the srcset or sizes attributes for images not embedded in post content (e.g. post thumbnails, galleries, etc.), by using the wp_get_attachment_image_attributes filter, similar to how other image attributes are modified.

If you are developing themes you also can create your own custom markup patterns by using the wp_get_attachment_image_srcset function.

Let’s look at an example.

Let’s say you wanted to generate a function that outputs the img tag for this image, but you only want to render the medium-sized image, and set a custom sizes attribute.

Instead of the default, which displays the image at 100% of the viewport at viewport widths of less than 799px, and 799px width on wider viewports, you want to set the sizes attribute to use the medium image width of 768px.

So that means you would need to set the sizes attribute to (max-width: 768px) 100vw, 768px.

function get_custom_responsive_image( $attachment_id ) {
	$img_src    = wp_get_attachment_image_url( $attachment_id, 'medium' );
	$img_srcset = wp_get_attachment_image_srcset( $attachment_id, 'medium' );
	echo '<img src="' . $img_src . '" srcset="' . $img_srcset . '" sizes="(max-width: 768w) 100vw, 768px" alt="Our custom responsive image">';
}

Then, you can call this function in any theme files that support PHP, so for example templates and template parts in classic themes, or block patterns in block themes.

In this example it’s being added to the footer-default pattern of the Twenty Twenty-Three theme, inside a group block at the top of the pattern. The image ID is 9, which you would pass to the function:

	<!-- wp:group {"align":"wide"} -->
	<div class="wp-block-group alignwide" style="padding-top:var(--wp--preset--spacing--40)">
		<?php get_custom_responsive_image( 9 ); ?>
	</div>
	<!-- /wp:group -->

If you look at this on the front end, you can see the custom sizes attribute has been used for this specific image.

If you test this out in Device mode, you will see that on device sizes below 768px, the image is displayed at 100% of the viewport width, and on sizes above 768px, the image is displayed at a width of 768px.

Conclusion

And that wraps up this introduction to the Responsive Images API in WordPress.

Happy coding