Andre Liem

How to load images responsively with WordPress

When building or modifying a theme for WordPress that is responsive you’ll likely encounter a small issue around image sizes.

How can you display the optimal image for each viewing device to optimize the speed?

This is a very important area to consider as you don’t want mobile users spending a lot of time waiting for an image to download. This article will walk through a common scenario where you need to display images in a gallery or carousel.

Define the image categories

In order to serve specific image sizes for different devices, you’ll  need to define the types of image categories to generate. Lets assume the simple scenario and you are targeting ‘mobile’, ‘tablet’, and ‘small desktops’ devices. The original image you upload to WordPress should be larger than all of these types as WordPress will resize down to these types.

An example for an image category would be:

  • name = gallery-mobile-thumb
    name will be used later in WordPress to retrieve that image type. It would be more powerful to actually use a dimension for the name like (320-thumb), but I won’t get into that now.
  • width = 320
    width should target the device width/viewport you are catering to. 320px in this case would be aiming to optimize the viewing experience for iPhones 3/4’s.
  • height = 210
    height should be set to maintain the aspect ratio of your original image. The aspect ratio for 320/210 =  1.5.
  • crop = false
    we don’t want our images to be cropped as we will make sure the administrator uploads photos that work for this aspect ratio.


Define the image sizes in WordPress

WordPress (2.9+) by default comes with a simple function add_image_size to define an image type. Using the image sizes defined in the previous section you’ll need to add a line for each one into your functions.php file.

With these three lines, images uploaded through the administration panel will be created in all these varieties.

Get a thumbnail image URL

So here is the step which requires a bit more thinking and unfortunately some verbose code. In your gallery template, or any file you wish to pull images, we’ll need to pull in the URLs for all the images types. Lets start with the basic example of pulling in a thumbnail for a standard template.

This code checks if the thumbnail exists and then retrieves the image object using the current ID of the post. With this object (or array to be precise) you can now pull the URL by using the first index.

Get all image URLs

This next part is building on the previous section by pulling in all your image types you defined before:

Now you have all four of your image types ready to use in the variables defined above. The full type is the original image that would typically be reserved for large desktop displays > 1200px.

Store the image URLs in HTML

This is where it gets trickier and for the sake of simplicity this example is as verbose as possible. Or in other words, this code could be refactored and cleaned up into a much more elegant library ;).

Lets assume you’re setting the background image of a <DIV>. What we’ll want to do is use the “data” attributes of each div to store a reference to the image url.

Now the HTML contains all the information we need to know about the image without actually fetching the image from the server.

Responsive Loading with JavaScript

The next part requires JavaScript and adopts the example JS code from CSS-Tricks

This piece of JavaScript accomplishes the following:

  • Bind to the window resize event
  • On resize, loop through the supported viewports from smallest to largest.
  • If the current viewport in the loop is >= than the current window width, stop the loop and select this as the viewport.
  • If none are larger (the viewport is larger than our largest image category), default to the largest viewport.
  • Loop through the gallery images.
  • Using the data attributes, get the image URL for the matching viewport.
  • Update the DIV’s background image.
  • Run the resize function on page load.

With these pieces of code your WordPress site can now responsively load images based on the given viewport. When it comes to a mobile experience, the difference in image size can mean the difference between a good and broken user experience.


  1. Hi Andre.

    I’m looking to implement this on page thumbnails, loading a smaller version on full size page, with three columns and larger thumbnails on mobile devices, single columns. Is this something that could be adapted to post thumbnails?


Leave a Reply

Your email address will not be published. Required fields are marked *