• Share this article:

Retina Images

As of October 2014, all premium ThemeFlood RapidWeaver themes have basic support for retina images. Retina images can be best described as images which have been optimised for retina displays and devices; like many of Apple's newer computers and handheld devices. Retina images are normally twice the size (length and height) of standard images, but they remain 72 dpi. When viewed on a retina display, the web browser will 'squash' the image down to fit the same size as a regular image. The end result is an image that will normally be sharper in appearance, with no visible pixels.

Pro's and con's of retina images

There are both positives and negatives towards using retina images in websites. Retina images may look great on websites for line art and larger photographs; when viewed on a retina display. However retina images can be particularly large (in terms of file size) and slow loading as a result. Too many retina images on the same page are likely to cause problems. At the same time images that have not been optimised for retina displays may appear more blurry in appearance. Retina displays will attempt to up-scale images to larger resolutions which can, on occasions, result in poorer image quality. A decision to optimise images in a website for retina devices should be considered carefully:

  • What sort of website is being built? Education, business, services, marketing, a blog?
  • How many images are there to optimise?
  • What proportion of visitors have retina displays? Use analytics to get this data.
  • Are retina-optimised images of importance to the function of the website?
  • Does the website author have the necessary time and resources to prepare retina images?
  • What's the average size (dimensions and file size) of the images in the website?

These are all questions to give careful consideration towards. There are plenty of instances where retina images may not be of significant benefit at the current time.

ThemeFlood theme implementation of retina image support

In ThemeFlood themes, we have incorporated the popular retina.js plugin. This plugin has been chosen because it is licensed for redistribution in themes, and is a simple and unobtrusive retina image plugin. It means that you do not need to buy any additional plugins or stacks. Everything you need is included in the theme already and retina image support is permanently enabled at all times.

Retina images can be used for the theme header or banner, and any images placed within the content or sidebar region of a page (including ExtraContent regions).

An attempt will be made to look for a retina version of your website logo (if one has been manually uploaded to the same directory that RapidWeaver published your standard logo image to). Unfortunately RapidWeaver does not presently support a drop-well in the site settings for a retina image. So this is something you would need to create and upload yourself via FTP.

How retina.js works

Retina.js works by firstly looking to see what device or web browser is viewing your webpage. If the web browser or device is identified as being a 'retina display', then the retina.js script will get to work. Otherwise on normal screens, retina.js will quietly retreat. On identified retina displays, retina.js will look at where each image in the webpage is coming from and will look to see if a retina version of the same image is available. So if for example you were using an image stored at:


retina.js will check the same directory and look for an image named the following:


As you can see, the important bit to get right here is the retina image always has '@2x' sandwiched between the file name and the file extension. If one of these retina images is found, then retina.js will swap it for the standard image, on retina images.

The way retina.js handles retina images is preferred by most web designers. Firstly it only takes effect on web browsers or devices identifying themselves as retina displays; therefore conserving bandwidth. It also means you can selectively 'retina-ise' some images but not all. Retina.js is clever enough to skip images that are lacking paired retina versions.

Important notes

A bug in RapidWeaver 5 will cause publishing of websites to fail and RapidWeaver can crash if you try to upload any files or resources with a '@' character in the file name. Obviously this greatly limits the ability to use retina images in RapidWeaver 5. The workaround solution is to warehouse all your images (upload them and save them separately from the RapidWeaver website you're building). This critical bug is believed to have been fixed in RapidWeaver 6.

Retina versions of your images need to be saved in the same location as the standard images. Retina.js is configured to only check the same directory that the standard format image is being served from. This is done to improve performance. Your retina versions of images need to be twice the height and width of the standard images, but should still be 72 dpi. All common image editing tools are capable of creating retina versions of images, so no specialist tools or software are needed for the task.

Lightboxes (like the Nivo Lightbox we bundle with ThemeFlood themes) have their own mechanism for sourcing retina versions of your images. Please refer to the lightbox documentation for details.

Checking of images for retina versions will only take effect on images embedded with a standard HTML image tag. Images embedded using other methods (like CSS backgrounds, canvases or iFrames) will not be 'retina-ised'.

It's normal for the browser console to log lots of error messages, in instances where no retina versions of images were found. These errors are for informational purposes only and will not harm the display of the website or your content.

Provide Feedback

Please use this form to provide feedback about this particular knowledgebase article. For example; to report broken links, errors or things you think could be worded better. We welcome all constructive feedback. All fields are required.


Feedback is submitted anonymously (unless you otherwise provide your name or contact details). We don't promise to reply to every feedback message received; neither is this a good place to request technical support. You can continue to request one-to-one support through the ThemeFlood website. See getting in contact for details.