Need help with angular-retina?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

120 Stars 34 Forks MIT License 191 Commits 1 Opened issues


Add support for Retina displays when using element attribute "ng-src"

Services available


Need anything else?

Contributors list


Replaces the AngularJS directive

by a version which supports Retina displays.

If the browser runs on a Retina display and the referenced image is available in double resolution, then load the high resolution version of that image from the server.

Build Status Code Climate


If you prefer to host Javascript files locally instead of using a CDN, install them with:

npm install angular-retina

Client usage

Into the main HTML code, add the required URLs from the CDN or include the files locally:

Please note, that angular-retina requires

or later.

In Javascript, initialize the main module for your AngularJS application:

var my_app = angular.module('MyApp', [...other dependencies..., 'ngRetina']);

In the body of any HTML code, access static referenced images using:

or reference the image using AngularJS's markup:

Note that when using this module, adding the element attributes

becomes mandatory, as the displayed image otherwise gets scaled to its double size.

Just use it in your HTML-code as you would use the common AngularJS directive ngSrc:

Alternative infix

When this library was written, Apple Inc. recommended to use

as infix, for images optimized for Retina displays. In late 2013, they changed their mind, and now suggest to use the infix

Since Apple's former recommendation, the proposed infix has been hard coded into some server-side libraries for image generation. Therefore, in version 0.3.0 of angular-retina, a configuration function has been added, which shall be used to set the infix to the newly proposed

– but of course only, if the server-side also supports it!
my_app.config(function(ngRetinaProvider) {

Hide images until loaded, avoiding "broken image" display

To hide (

opacity: 0
) images until the library has determined what resolution to use, set the
and the image has finished downloading, use the following config:
my_app.config(function(ngRetinaProvider) {

Images with embedded hash

When using a framework that embeds a digest/hash to the asset URL, the problem is that a high-resolution verison would have a different hash and would not follow the usual pattern that ends with @2x. Instead the hash is added at the end, i.e.

/images/[email protected]{hash2}.jpg
, so the automatic detection of image URL would fail.

The solution is to supply the high-resolution URL image from the outside of the library using the


On the server

Applications supporting Retina displays should include two separate files for each image resource. One file provides a standard-resolution version of a given image, and the second provides a high-resolution version of the same image. The naming conventions for each pair of image files is as follows: + Standard:

+ High resolution:

If the browser runs on a high-resolution display, and if the referenced image is available in high-resolution, the corresponding

tag is interpreted, such that the image in high-resolution is referenced.

This module can also be used to reference static image urls, to load the high resolution version on Retina displays.

Same Origin Policy

In order to verify if the image exists in high resolution, angular-retina invokes a HEAD request with the URL of the high-res image.

For security reasons, Javascript may not access files on servers starting with a different domain name. This is known as the Same Origin Policy. Therefore please ensure, that all images accessed through

can be loaded from the same domain as the main HTML file.

Release History

  • 0.1.0 - initial revision.
  • 0.1.3 - fixed problems with minified JS code.
  • 0.2.0 - using sessionStorage instead of $cacheFactory to boost performance.
  • 0.3.0 - added
    to configure the used infix for Retina images.
  • 0.3.1 - added a noretina attribute support to conditionally disable the "retinification" for an element.


© 2015 Jacob Rief

MIT licensed.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.