Respimage

#respimage respimage is a fast, lightweight and robust responsive images polyfill, that saves the users bandwidth by utilizing smart resource selection algorithm. It implements the srcset/sizes attributes as also the picture element. Unlike other responsive images polyfills respimage plays nicely with your graceful degradation / progressive enhancement and image SEO strategy.

##Download and Embed Simply download the respimage.min.js script and add it to your website or bundle it in your normal JS.

<script src="respimage.min.js" async=""></script>

respimage will automatically run and polyfill all images. So you can simply start writing responsive images.

In case you want to include respimage only if the browser doesn't support responsive images you can add the following inline script at the top of your head (before any stylesheets or any blocking JS, This should be added as inline script and not inside of an external script.):

<script>
function loadJS(u){var r = document.getElementsByTagName( "script" )[ 0 ], s = document.createElement( "script" );s.src = u;r.parentNode.insertBefore( s, r );}

if(!window.HTMLPictureElement){
	document.createElement('picture');
	loadJS("respimage.min.js");
}
</script>

In case you need to support IE8 and want to include the script at the bottom you need to use either the html5shiv or add at least the following script inside your head element:

document.createElement('picture');

Also note, that only IE8 in strict mode is supported. In case you need to support IE8 compatibility view or IE7, please use the oldie plugin.

###Mobile support

For mobile support it is crucial to set the viewport meta tag to device-width

<meta name="viewport" content="width=device-width, initial-scale=1" />

####Install via bower

$ bower install respimage --save

####Install via npm

$ npm install respimage --save

##Markup Examples Responsive images can be technically differentiated between 2 types.

• srcset with source descriptors (let the browser choose the right image based on screen size/resolution, bandwidth…):
  • density descriptor (x) (for static image sizes, Retina vs. normal resolution)
  • width descriptor (w) and the corresponding sizes attribute (for flexible, responsive / adaptive images (automatically also includes Retina optimization)
• and the picture element with its source[media] children (gives the author control about what srcset should be chosen by the browser depending on specific media queries)

###srcset with the density x descriptor The x descriptor is natively supported in Firefox 38, Chrome 34+ and Safari 7.1+. All other browsers will be polyfilled. <br />Note: You must not mix the w and the x descriptor in one srcset attribute!

<img
	srcset="http://placehold.it/350x150 1x,
		http://placehold.it/700x300 2x"
	src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
    alt="Static content image" />

load example

###srcset with the width w descriptor and the sizes attribute The w descriptor is in Firefox 38 and Chrome 38+. All other browsers will be polyfilled. <br />Note: You must not mix the w and the x descriptor in one srcset attribute!

<img
	srcset="http://placehold.it/466x200 466w,
		http://placehold.it/700x300 700w,
		http://placehold.it/1050x450 1050w,
		http://placehold.it/1400x600 1400w"
	sizes="(max-width: 1000px) calc(100vw - 20px), 1000px"
	src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
	alt="flexible image" />

load example

###The picture element The picture element is currently only supported in Firefox 38 and Chrome 38+. All other browsers will be polyfilled. To support IE9 all source elements have to be wrapped inside of an audio or hidden video element:

<picture>
	<!--[if IE 9]><audio><![endif]-->
	<source
			srcset="http://placehold.it/500x600/11e87f/fff"
			media="(max-width: 450px)" />
	<source
			srcset="http://placehold.it/700x300"
			media="(max-width: 720px)" />
	<source
			srcset="http://placehold.it/1400x600/e8117f/fff"
			media="(max-width: 1100px)" />
	<source
    		srcset="http://placehold.it/1800x900/117fe8/fff" />
	<!--[if IE 9]></audio><![endif]-->
	<img
			src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
			alt="image with artdirection" />
</picture>

load example

The art direction approach of the picture element and the descriptor approach can also be mixed:

<picture>
	<!--[if IE 9]><video style="display: none;"><![endif]-->
	<source
			srcset="http://placehold.it/525x225 1.5x,
        	http://placehold.it/350x150 1x"
			media="(max-width: 380px)" />
	<source
			srcset="http://placehold.it/1400x600/e8117f/fff 1.5x,
        	http://placehold.it/1024x439/e8117f/fff 1x"
			media="(max-width: 1050px)" />
	<source
	    srcset="http://placehold.it/2100x900/117fe8/fff 1.5x,
            http://placehold.it/1400x600/117fe8/fff 1x" />
	<!--[if IE 9]></video><![endif]-->
	<img
        src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
        alt="image with artdirection" />
</picture>

load example

##API ###respimage function In case new responsive images are created and dynamically added to the DOM simply invoke the respimage method.

window.respimage();

Here an extended example how this could look like in a jQuery environment.

$("div.dynamic-context").load("path-to-content.html", function(){
	if( window.respimage ) {
    	respimage();
    }
});

In case you are dynamically changing relevant attributes (srcset, sizes, media) on responsive images or their associated source elements, you need to call respimage with an additional argument:

respimage({elements: [imageElement], reevaluate: true});

In the unlikely case you want either remove the srcset of an img (not of an source) or want to directly change the src of an responsive image the additional src or srcset option has to be set (Note: In most cases, you don't want to do that!).

var $imgs = $('img').removeAttr('srcset');

respimage({elements: $imgs, reevaluate: true, srcset: true});

//or for src

var $imgs = $('img').attr('src', 'some-img.jpg');
respimage({elements: $imgs, reevaluate: true, src: true});

Note: The reparse option was renamed with version 1.4.0 to reevaluate to better match the option used by picturefill.

In case you are not supporting IE8 we recommend to use the Mutation plugin instead of using this API (It fully polyfills also the DOM APIs and makes additional calls to respimage automatically for you).

Browser Support

respimage supports a broad range of browsers and devices. It is actively tested in the following browsers and devices IE8+, Firefox (ESR and current), Safari 7.0+, Chrome, Opera, Android 4.1+ and IOS 7+, but should work in a lot more browsers/devices. IE6 and IE7 are only supported with the oldIE plugin.

##Troubleshooting and bug reporting In case of any problems include the respimage.dev.js into your project and open your JS console. In case you think you have found a bug, please create a testcase and then report your issue. Note: You should not use the dev build inside your production environment, because it is a lot slower.

*Note: It is highly recommended to test with the .dev.js file, especially if you are using responsive images the first time or you start a new project setup. The respimage.dev.js file can give you some useful hints in the console. About 80% of all tutorials suggest wrong markup examples! Also note: That our respimg debugger can't check every possible error.

##Plugins

respimage has some really nice extensions/plugins to improve standards support even more. In case you want to use a CDN, you can use the combohandler service provided by jsDelivr:

<script>
function loadJS(u){var r = document.getElementsByTagName("script")[0], s = document.createElement("script");s.src = u;r.parentNode.insertBefore( s, r );}

if(!window.HTMLPictureElement){
	document.createElement('picture');
	loadJS("http://cdn.jsdelivr.net/g/respimage(respimage.min.js+plugins/mutation/ri.mutation.min.js+plugins/intrinsic-dimension/ri.intrinsic.min.js+plugins/typesupport/ri.type.min.js)");
}
</script>

###The intrinsic sizes / dimensions - Plugin The intrinsic dimension plugin extends respimage to add the intrinsic dimension based on the descriptor (and the sizes attribute) and the density of the source candidate to the width content attribute of the image element.

###The Mutation - Plugin This plugin automatically detects new responsive images and also any changes to srcset/media and sizes attributes. It also implements the corresponding DOM properties for those attributes.

###The typesupport - Plugin The type support plugin adds type support detection for the following image file types: apng, JPEG 2000, JPEG XR, WEBP

###The oldie - Plugin Respimage supports IE8+ (including) out of the box. In case you need to support IE6/7 or any IE in compatibility view or quirksmode use the oldie plugin.

##Known issues/caveats/

• Browsers without picture and srcset support and disabled JS will either show the image specified