Retina Images

Automatically serve high-res images, to those who'll appreciate them.

View project on GitHub Download Retina Images (v1.4.0)

Mouse-over to see the effect of Retina Images
This demo actually replicates what happens on retina devices

Back to top

About Retina Images

Retina Images serves different images based on the device being used by the viewer.

Once setup on your website (very simple!) all you have to do is create a high-res version of each image you would like optimised for retina screens and all the work is done for you. You don’t even need to change any <img> tags (providing they have a height or width).

Example of non-retina image
Without Retina Images.
Example of retina image
With Retina Images.

Back to top

How it Works

  1. When the page loads on the viewers device, a cookie holding the devicePixelRatio is set by either JavaScript or CSS (if JS is disabled).

  2. When an image is requested by the server, the .htaccess file tells retinaimages.php to serve the image instead.

  3. retinaimages.php then checks for the following conditions:

    • A cookie holding devicePixelRatio exists.

    • The value set in the cookie is greater than 1.

    • A high-res version of the image exists.

  4. If any of the above are false, it will send the regular image. Otherwise, the high-res image is sent in its place.

Back to top

Setup Your Server

Installing Retina Images is really quite simple:

  1. Drop the retinaimages.php and .htaccess file into your document-root (usually public_html).

    Warning! Do not overwrite a this file if it already exists, simply copy the contents into your existing one.

  2. In the <head> section of each page before any CSS put the following JavaScript: 

    <script>(function(w){var dpr=((w.devicePixelRatio===undefined)?1:w.devicePixelRatio);if(!!w.navigator.standalone){var r=new XMLHttpRequest();r.open('GET','/retinaimages.php?devicePixelRatio='+dpr,false);r.send()}else{document.cookie='devicePixelRatio='+dpr+'; path=/'}})(window)</script>

  3. Straight after your opening <body> tag put the following CSS: 

    <noscript><style id="devicePixelRatio" media="only screen and (-moz-min-device-pixel-ratio: 2), only screen and (-o-min-device-pixel-ratio: 2/1), only screen and (-webkit-min-device-pixel-ratio: 2), only screen and (min-device-pixel-ratio: 2)">#devicePixelRatio{background-image:url("/retinaimages.php?devicePixelRatio=2")}</style></noscript>

    Note: This must go inside the body tag.

  4. For every image that you would like to have served at high-res, create an image at twice the size and save it with @2x at the end of the filename (before the file extension). See the example.

Back to top

HTML Images

HTML images are the easiest to get setup, chances are they will work without any change.

All you have to worry about, is that an image with a high-res counterpart must have a width or height (or both) attribute specified.

<img src="my-image.png" alt="My awesome image" width="300" height="90">

Back to top

CSS Images

CSS images will usually require some work, all CSS images must have a suitable background-size property to work correctly. Below are three of the simplest methods to contain your retina background images.

CSS Background Images

A static pixel value equal to the size of the regular (non-retina) image.

.some-selector {
    background-image: url("my-image.png");
    -webkit-background-size: 300px 90px;
       -moz-background-size: 300px 90px;
         -o-background-size: 300px 90px;
            background-size: 300px 90px;
}

Image Replacement

If the (standard size) image is the same size as the box you may either the following for convenience as they will product the same result.

.some-selector {
    background-image: url("my-image.png");
    -webkit-background-size: 100% 100%;
       -moz-background-size: 100% 100%;
         -o-background-size: 100% 100%;
            background-size: 100% 100%;
}
.some-selector {
    background-image: url("my-image.png");
    -webkit-background-size: cover;
       -moz-background-size: cover;
         -o-background-size: cover;
            background-size: cover;
}

Back to top

File Example

Served to non-retina devices.

Example of regular image
settings.png59px × 59px

Served only to retina devices.

Example of double size retina image
settings@2x.png118px × 118px

Benefits and Drawbacks

Benefits

  • Only one image is downloaded by the viewer.

  • All standard raster images (.jpg, .png, .gif & .bmp) are able to be served as high-res.

  • Fallback to regular image if high-res image isn’t available.

  • Fallback to regular image if JavaScript and CSS or Cookies are disabled.

Back to top

Drawbacks

  • <img> tags must have either a width or height attribute specified.

  • CSS background images must have a background-size property. See CSS Images for details.

Back to top

Plugins

WP Retina 2x by Jordy Meow for WordPress

Recommended for WordPress

“Make your website look beautiful and smooth on Retina (high-DPI) displays.”

Note: These are plugins that I am aware of that use Retina Images. If you have developed (or are developing) a plugin that uses Retina Images, send me a email and I may link it up here.

Back to top

So Long, and Thanks for All the Fish

Twitter
for releasing Bootstrap which the style of this page is built on.
Matt Wilcox
for creating adaptive-images which spawned my idea to create this.
Benjamin Nathan
for the settings icon used in the file and display (only on small-screen and touch devices) demos above.
H5BP Team
for creating H5BP which the structure of this page is built on.
Marshall Bock
for the iPhone 4S mockup used in the demo above (only on large-screen and non-touch devices).