Sun, Fun, and Learning All Courses for Only $9.99

Nov 27, 2012

Coding for Retina Displays with RetinaJS Tutorial

Coding for Retina Displays with RetinaJS Tutorial

With Retina displays quickly becoming the standard on phones, tablets and laptops, it is more important than ever to make sure your website looks great on high-resolution screens.

The cure for blurry and pixelated graphics on your website is to use high-resolution images. However, the problem with hi-res images is two-fold: by their nature, they carry a much larger filesize, and their benefits are lost on normal-resolution screens.

The solution is to only serve high-res images to hi-res devices. Unfortunately, web browsers currently don't have a built-in mechanism to request high-resolution images this way. RetinaJS helps solve this problem.


RetinaJS is an open source javascript library that makes it easy to serve high-resolution images to devices with retina displays. When your users on high-resolution devices load a page on your website, it checks each image on the page to see if there is a high-resolution version of that image on your server. If a high-resolution variant exists, the script will swap in that image in place of the normal resolution image.

How to use RetinaJS

1. Download the script

Go to and click the "Download Zip" link. Open the zip file and copy the 'retina.js' file to where you keep your website's javascript file.

2. Install the script

Add the script to your website by adding a <script> tag for retina.js to the bottom of the page, right before your closing </body> tag.


  <script src="/path/to/retina.js"></script>  

3. Add high-resolution images to your website

By convention, RetinaJS looks for images on your server that use the "@2x" naming convention. To start using high-resolution graphics on your website, simply upload images that follow this naming pattern.

For example, if your logo image is located at "/images/logo.png" and the markup for this image looks like this:

    <img src="/images/logo.png">

RetinaJS will automatically look for a corresponding image located at "/images/logo@2x.png". If it finds the @2x image on your server then it will load that onto your web page, effectively transforming your logo's markup to look like this:

    <img src="/images/logo@2x.png">


  • RetinaJS automatically scales down high-resolution images to the dimensions of the original image. Due to the nature of the scaling, your high-resolution image variants should have dimensions that are an even multiple of the original image's resolution. For example, if /images/header.png is 400px x 200px, then /images/header@2x.png dimensions should be exactly 800px x 400px.
  • For small images such as logos, it can be beneficial to use high-res variants that are 4x the original dimensions. On phones and tablets, this will keep the image sharp even if the user zooms into the page. For example, if /images/logo.png is 100px x 50px, then /images/logo@2x.png dimensions could be 400px x 200px.

About the project

Retina.js is an open source script, created by the Boulder-based digital agency Imulus. You can help them in their project on Github.