One of the biggest factors of responsive design and development is the overall weight of your page. The focus of your responsive site is not just the design and experience according to your media, but also what content is loaded to your targeted media.

The power of CSS3 Media Queries is enormous, but it is also very limiting when it come’s to loading of specific content for specific devices and browser widths. You can use media queries to hide and show images, but images which are hidden with CSS are still loaded in the browser, which hurts load times and performance of your page. There are some options you may use in the future with the new HTML5 srcset attribute, however it’s still currently only a draft within the w3c and no browsers currently support it. You can read more about the srcset attribute here

But for now we must to rely on javascript to dynamically load images depending on browser width and pixel densities.

Say hello to image-swap.js, image-swap.js detects your device or browser width and swaps the image source with the image you defined at the specific width.



Setting up image-swap.js is simple! We use the HTML5 srcset attribute which soon will be supported by browsers and devices, and we define our images sources, browse widths, and even high pixel density screens.

Make sure you are running jQuery 1.7 or greater, and link the image-swap.js file in the head of your page.

<script src="image-swap.js" type="text/javascript"></script>


To initiate image-swap.js it can be done with this simple call:

$.fn.imageSwap({imageContainer: '.swap-img', breakpoints: [480,768,1024,1440]})

Make sure you have your breakpoints defined within the ‘breakpoints‘ option, and the class name or id of the image must match the imageContainer option.

Here’s how the image source should look:

<img src="#" srcset="
    imageswap-480.png 480w,
    imageswap-480-2x.png 480w 2x,
    imageswap-768.png 768w,
    imageswap-1024.png 1024w,
    imageswap-1440.png 1440w"

image-swap.js detects your device or browser width and loops through each of the image sources within the srcset attribute, then applies the proper image. It also detects the pixel density of your screen. Within the srcset attribute if you apply the ‘2x’ next to the width property that image will be loaded for high pixel density devices and screens.


You can also pass the following options when you call

  imageContainer: string (image class or id)

This is a string which will be passed into a jQuery selector. And is finding the class or id of the image that will be targeted to run image-swap.js. (default is set to ‘.swap-img’)

  removeImage: true or false

image-swap.js has the ability to hide the HTML IMG tag and replace the source with a 1×1 transparent .gif if no images were found for that specific breakpoint. If this is set to false, and no image is found for a specific browser or device size a broken image element will be shown. (default is set to true)

  createNewImage: true or false

If an image is found at another width, after the image has been hidden, image-swap.js will display the image again with the right image source. (default is set to true)

   loadBestAvailable: true or false

If on a high pixel density screen and there is no ‘2x’ image defined. image-swap.js will load the lower resolution image. Vice-versa for when on a normal pixel density screen and only ‘2x’ images are defined. (default is set to true)

   monitorPixelDensity: true or false

Will now monitor the browser window for changes with the device’s pixel ratio. When the user moves the window to a high density screen to a normal density screen an even will trigger and apply the appropriate image source.  (default is set to fasle)

  interval: milliseconds

How frequent does the script run on window resize.

Help contribute

If you have an idea for image-swap.js, or wish to submit a fix for a bug you noticed. You can help collaborate and follow image-swap.js on Github.