Skip to content
jQuery plugin to replace images for retina displays.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

What is retina-replace.js?

  • retina-replace.js is a jQuery plugin for replacing out css background-images and img tag src's for a high quality retina version
  • Only runs on devices with a devicePixelRatio > 1
  • Preloads images before updating to alleiviate flashing when replaced

By default _2x is appended to the image url so /img/foo.jpg would become /img/foo_2x.jpg both the suffix and retina url generating function can be overriden on intalization.

Once an element's image has been replaced with its retina version the attribute data-retina is set to complete for example <img src="/img/foo.png" data-retina="complete" />

Using retina-replace.js

Simply call the retinaReplace function on the targeted elements

$('#foo, #bar').retinaReplace();

if using retina-replace.js to replace background images on elements then the add the following css to your stylesheet

[data-retina=complete] {
    -webkit-background-size: 100%;


Name Type Default Descritpion
suffix string _2x The default string to append to the current image url
generateUrl function appens the suffix value to the current url The method used to generate the url for the retina image. Retrives two arguments, the current `element` and `url` determined from ether the image src (if an image tag) or background-image on all other elemnts


To quickly mark a element to be replaced just add data-retina="true" and any image source or background image will be replaced on retina enabled devices

<img src="/img/foo.jpg" data-retina="true" width="40" height="30">
<div class="foo-with-background-image" data-retina="true"></div>


  • Add some examples of overriding the url generator function
  • Possibly llow replacement of images with svg images?
You can’t perform that action at this time.