Make your existing images responsive without creating new images.

Responsive Img swaps out an image's src attribute based on its container's width when the DOM is ready and when the browser is resized.

Using a PHP file, Responsive Img creates new images on the fly the first time they're needed and puts them on your server.

Therefore, you can add Responsive Img to any site, without creating new images.

Responsive Img takes pixel ratio into account and uses larger images for Retina display and displays with other pixel ratios.

Responsive Img works on background images, too.

As of version 1.4, Responsive Img swaps out CSS background images in addition to regular images.
See the background image example.

Method 1

No extra HTML or CSS markup

First, add responsiveImg.js (6kb) and responsiveImg.js.php (4kb) to your server and include the responsiveImg.js script in your head tag.

Then call the Responsive Img plugin on any image(s) that you want to become responsive. See the How To.

When the DOM is ready and any time the browser resizes, Responsive Img replaces each image's src attribute with a new image, based on the size breakpoints specified when you call the plugin.

If the new image doesn't exist on the server, Responsive Img will create an image at the new size. The image gets saved in the same folder on your server as the original image, so it will never need to be created again.

Using Method 1, the viewable image will load faster, but the original, full-size image still has to load in the background, meaning this won't speed up overall page load time. For that, see Method 2.

Method 2

A little bit of HTML markup

Using Method 1, the original image file always gets loaded (even after Responsive Img swaps in a smaller image, which happens right away).

To prevent delaying page load, follow Method 1, but change a little markup on the images.

Set the image's src attribute to a placeholder image (a loading icon or a single pixel image are good options), and then create another attribute (data-src is a good one to use) for the real image's source. Then set the srcAttribute option when you call responsiveImg(). See an example.

How To

Responsive Img uses only 2 files.

The plugin can be implemented with one script include and one line of Javascript.

<script src="js/responsiveImg.js"></script>

Default Options

Breakpoints are key/value pairs of filename suffixes and width breakpoints in pixels.

Pairs should be wrapped in brackets and separated by commas (leave off the last comma).

srcAttribute is a string for the attribute that holds the image's source.

This defaults to src, but should be overridden if the src attribute holds a placeholder image.

pathToPHP is a string for the path from the file that calls Responsive Img to the PHP file that creates new images.

This value is js by default, because I like the PHP file and the Javascript file both in the same js folder.

createNewImages is a boolean that lets you override the default option to create different sized images on the fly.

jpegQuality sets the image quality when creating new jpegs. The default is 90. (This was changed in version 1.4. It used to be 100.)

callback is an optional function that will run after Responsive Img finishes switching the image. (This was added in version 1.4.)

breakpoints : {
srcAttribute : "src",
pathToPHP : "js",
createNewImages : true,
jpegQuality : 90,


  • jQuery
  • PHP
  • Writable image folder (proper directory permissions)

No Options

If no options are specified, Responsive Img defaults to breakpoints that are roughly device sizes.

360 pixels (with the suffix "_small")
780 pixels ("_medium")
900 pixels ("_large")

In addition, Responsive Img assumes the php file to create new images is in a folder called "js."

<div style="width:50%;">
    <img id="img1" src="images/leaf.jpg" style="max-width:100%;" />

Custom Breakpoints

You can choose what sizes to swap in new images by specifying custom breakpoints, each with a unique filename suffix.

The format is key/value pairs, with the suffix string as the key and the breakpoint width as the value.

<img id="img2" src="images/image.png" style="width:49%;" />
<img id="img3" src="images/image.png" style="max-width:49%;" />

Placeholder Image

For faster loading, especially on mobile phones, you'll need to set the src attribute of each image to a loading icon or a single pixel image (or whatever you want, obviously). Then use another attribute (I recommend data-src) to store the original src value.

Unforutnately, changing the src value, even before the image is loaded, still causes the browser to load the image. The only way to prevent the original image from loading is to change the src value in the original HTML.

Note Originally, placeholder images weren't getting replaced if the original image was smaller than the breakpoint size. This was fixed in version 1.3 on 3/2/13.

$("#img4").responsiveImg({ srcAttribute:"data-src" });
<img id="img4" src="images/ajax-loader.gif" data-src="images/flower.jpg" style="max-width:100%;" />

CSS Background Image

To replace a CSS background-image property instead of an image's source, call the plugin on any element (well, anything but an img element) and use the srcAttribute option.

<div id="div1" data-src="images/leaf.jpg" style="background:url(images/leaf.jpg) center no-repeat; width:50%; height:200px;"></div>

Images Won't Size Up

If an image is smaller than a breakpoint size, Responsive Img will NOT size that image up. (The image would lose quality.)

Note This was originally an issue, but it was fixed with an update on 11/26/12.


Retina Display (and other pixel sizes)

Responsive Img takes pixel ratio into account and serves up the correctly-sized image, adjusted for the display (1.5x and 2x pixel sizes).

Note This functionality was added in version 1.2 on 12/20/12.


Keep It Easy

An easy way to use Responsive Img is to call it on images with a specific src and an alternate src attribute that exists.

In the example shown here, Responsive Img would affect all images with loading.gif as their src and with an attribute called data-src that contains the actual image's source.

$("img[src=loading.gif][data-src]").responsiveImg({ srcAttribute:"data-src" });
<img src="images/loading.gif" data-src="images/image.jpg" />
Change Log

Change Log

11/23/13 Removed 'baseurl' method for image path and plugin will now find the relative path with php instead (1.5)

6/15/13 Added CSS background functionality, added a callback option, and set default jpegQuality to 90 (1.4)

3/2/13 Fixed placeholder image bug: plugin will now switch to the original image if it's smaller than the breakpoint when using a placeholder image. Plugin also now fires on window load as well as resize (1.3)

12/22/12 Added a jpeg quality option (1.25)

12/20/12 Added support for pixel ratio, fixed an iOS bug (1.2)

11/26/12 Fixed image size up issue: plugin won't create new images that are larger than the original image (1.1)

10/20/12 Initial plugin (1)


drewbrolik, reblutus, ChrisKam

Contact Me

Questions? Thoughts? Etc?

I'm Drew Thomas, and my company is Brolik.


This plugin was created for Brolik's Leverage CMS. /