Supporting Retina images in a WordPress theme

Mac and iPhone

Since Apple launched the iPhone 4 in 2010, high resolution displays have been standard in most new devices. Apple calls it the Retina display, and we’d guess most people will refer to it as such rather than HiDPI or other more accurate descriptions.

So how does it work? It’s all about pixel density – how many pixels you can fit into a certain area of screen without increasing its size. The more pixels, the sharper the image.

At the time, Apple simply doubled the amount of pixels in the screen – in this case, from 480 x 320 to 960 x 640. Other manufacturers followed and screen sizes and pixel density grew.

Why optimise for Retina images?

gravatar retina
Image courtesy of

Because it looks brilliant on the screen? Well, yes. But there’s a more important reason – it looks really poor if it’s not optimised.

Once this particular genie was let out, there wasn’t really a choice but to start optimising your images. Can’t tell the difference? You will. This image shows two Gravatars as viewed on a Retina device. The image on the left is not Retina-ready. The one on the right is.

What about bandwidth? Don’t you need more?

Yes. Yes you do. However, bandwidth isn’t such an issue in these days of high-speed 3G, super-fast 4G and wow-that’s-quick broadband.

Bear in mind that all images should be optimised for file size before uploading to a website anyway.

How do you do it then?

Quite simply, you double the size of the image. The browser then shows the double size image in the same dimensions as the normal size image.

There’s two parts to supporting Retina images – creating them, and detecting a need for them.

Creating Retina images

This is the first part. It doesn’t matter if you can detect the screen type – if there aren’t any Retina images to display, you’re scuppered.

You’ll need the original image to be twice the size that you’re going to show on the site. If the image displays as 600 x 300, you’ll need to have an original image of 1200 x 600.

The code below will create Retina images for each image that’s uploaded. Add it to your theme’s functions.php file.

The first part of the code uses the WordPress wp_generate_attachment_metadata filter to add to the uploaded image’s metadata.

The next part creates the actual Retina images – one for each size that the site will generate anyway. Unless the original size is smaller than the Retina size – in this case it will skip it. It appends Apple’s high-resolution modifier, @2x to the filename of all retina images created.

But what about if you delete an image? Well, let’s clean it up by deleting the extra images we created.

So there you have it. Retina images created for your WordPress theme. Don’t forget that you should use a child theme to make any changes so they aren’t overwritten when the theme is updated.

Serving Retina images

So we have our Retina images ready for serving. But we don’t want to serve them if it’s not necessary – despite what we said about bandwidth above, this will scoff your bandwidth and slow your site down. So we need to detect whether a Retina image is necessary and if so, replace the image URL with the Retina image URL.

There is a free script that will do all this for you. Built by Imulus, it’s called retina.js and you can get it from

Install this script in your WordPress site (the proper way!):

Obviously, change the path to the location where you have the script on your server. Note that the last argument in the wp_enqueue_script function is true – this will load the script in the footer of the page, just above the </body> tag.

Retina.js works by first checking the pixel density of the device used on each pageload. If it’s a Retina device, it will then check every image in the page to see if a Retina version of that image is available  – remember the @2x we added to the filename? If it is available, the script will append @2x to the filename and the Retina image will be displayed. If not, the original image will be displayed.

So there it is. That’s how to create Retina images in a WordPress theme, and how to detect them and display them.