jQueryHDimg™ 1.1.3 Download

[ jQuery HDimg ]
jQuery plugin to serve double size images on Retina and other high resolution display

This plugin is useful to auto load a double size image for high resolution displays. Simply it search for an img with a specific (that you can choose) suffix to use in case of Retina or other high density displays.


To see properly this plugin in action you need 2 different devices to see the difference between a common or high res display.

Image Assigment Demo

Img1 Img2 Img3

Image Replacement Demo

Img1 Img2 Img3

Basic Usage

#1 - Include jQuery and jQueryHDimg Plugin

To use jQueryHDimg first include jQuery library and plugin inside your document.
Best pratic is better to include the files before the closure body tag (</body>) but is also good inside the <head>

<script src="your-libs-path/jquery.min.js"></script>
<script src="your-plugin-path/jquery.HDimg.js"></script>

#2 - Generate images

The second thing to do is prepare all images you need to affect by the plugin. Rename your original image as you want, then make the double image and rename it with a specific suffix as @2x.
A sample of image renaming can be img-01.jpg for the original image and img-01@2x.jpg for high density display image.
WARNING: both images must be placed on the same directory!
You can choose the suffix you want, but if you customize the suffix, you must declare it with the specific plugin option.
To learn more about custom suffix usage see the proper chapter below.

#3 - HTML Markup

If you use the default options, you don't need to do anything in you html code, simply add the images as usual

<img id="image1" src="img/img.jpg" alt="Image Title">

#4 - CSS

To obtain a correct image substitution (both images, normal and double, with the same sizes), some css coding is needed.
To do this you must assign an univoc ID to each image and use it for specify sizes by css rules.
On the example above I used id="image1" so the css rule can be something like this:

#image1 {width: 100px; height: 100px;}

If you have more images with the same size, you can use a class instead many different ID.


It's possible to use this plugin for a single image or for all images inside a dom element.
On exsample below each image inside the div with attribute id="#retina" will be affected by the plugin.

$("#retina img").HDimg();

On exsample below all images inside the document will be affected by the plugin.


Options & Advanced usage

This plugin haven't many option that make you crazy to use it.
The dafault options are sufficient to make a great job, but if you need some different settings you can use the following custom options

Options List

Option Name

Option Allowed Values

imgReplacement boolean - default: true - accepted: true/false (option added from version 1.1.3)
imgAssignment boolean - default: false - accepted: true/false
densityLevel int - default: 1.25 - accepted: 1.25 - 1.3 - 1.5 - 2
imgSuffix string - default: "@2x" - accepted: any string you want
autoResize boolean - default: false - accepted: false, true
This property works only if imgReplacement option has value true
addClass boolean/string - default: false - accepted: false, true and any string you want as class name.
devForce boolean - default: false - accepted: false/true (option added from version 1.1.2)

Image Replacement or Assignment?

This plugin works in two different ways: replacement and assignment.

Image Replacement

The default way is Replacement technique that works leaving the image unreplaced in case of common display and replacing it only if necessary.
This technique, in case of high density display, force the dom to load before the original image and then the double size one.
Replacement allow you (if you want) to use the auto resizing of the images, without any css rule. For do this use the option "autoResize: true" (see below the usage).
Replacement is the dafault technique so you don't need to specify it on plugin options

Image Assignment

Because this plugin is thinked as "mobile first" we provide the Assignment technique, that works charging only the image that is needed for the current scenario and not before the original image (with bandwidth consuming) and then replacing it, if is needed by the high resolution display.
For this reason you must put the original img url on a data attribute and not inside src attribute.
The plugin executes a media query and then assigns the right image to the src attribute.
This method needs the css size rules.

If you use the image assigment (see below the difference) place inside the page all the img tags you need but leaving empty the src attribute, and specify the original (not duoble) image url with the data attribute data-src="".

<img id="image1" data-src="img/img.jpg" src="" alt="Image Title">

WARNING: if you choose the assignment technique instead the default replace technique, remember that this cause a W3C validation error for the empty "src" attribute.

Assigment technique can be declared with the option imgAssignment: true or with the option imgReplacement: false

$("#demo > img").HDimg({ imgAssignment: true });

is equivalent of

$("#demo > img").HDimg({ imgReplacement: false });

Display Density Level

This option allow you to specify a particular density to start the image sunstitution.
The default value is 1.25 but you can specify alternative values such as 1.3 - 1.5 and 2
See the example below:

$("#demo > img").HDimg({ densityLevel: 1.25 });


The default suffix for the double size image is @2x but you can customize this parameter with the option imgSuffix
You can use the suffix you want.
In the example below will be used the prefix _double. Using this prefix, the double size image must be renamed in this way: imgname_double.jpg

$("#demo > img").HDimg({ imgSuffix: "_double" });

Adding Class

By the option addClass it's possible to add a particular class to the double size img
The option accept boolean value (true and false) or a string used as class name. If you use true value instead a class name, will be used the default class hd-image

$("#demo > img").HDimg({ addClass: "doubleImage" });

Auto Resize

By the option autoResize it's possible to resize the image without any css rule. This option is available only if imgReplacement is turned on true value.
This option accept only boolean value (true and false). Default value is false.

$("#demo > img").HDimg({
imgReplacement: true,
autoResize: true


Option added from version 1.1.2

By the option devForce it's possible to force the plugin to switch images to hd version.
This option is useful during site developing to see how your site appears once the images are changed by plugin.
This option accept only boolean value (true and false). Default value is false.

$("#demo > img").HDimg({
devForce: true

devForce Demo

As you can see, the following 3 images are loaded as 2x also in non hd displays

Img1 Img2 Img3

Old Explorer Caveat

To provide old ie version compatibility it's necessary to use two different polyfills:
# respond.js
# matchmedia.polyfill.js