Retina-ready Responsive Image Plugin For jQuery

Just another jQuery based retina-ready responsive image solution that helps you load in proper images dynamically for different screen sizes, depending on the viewport or parent container's width.

Basic usage:

1. Include jQuery library and the jQuery Responsive Image plugin on the html page.

<script src="//code.jquery.com/jquery-1.11.3.min.js"></script>
<script src="jquery.responsiveImage.js"></script>

2. Include the jQuery debouncedresize plugin to load in images dynamically once after a window resize.

<script src="jquery.debouncedresize.js"></script>

3. Insert images with different resolutions into the container using data-src attribute. Breakpoints start from 0px to 399px, 400px to 599px, 600px to 799px, 800px to 999px and large image above 1000px.

<span class="picture" data-alt="foo" data-title="bar" data-class="img-responsive">
  <span data-src="400x200.jpg"></span>
  <span data-src="600x300.jpg" data-min-width="400"></span>
  <span data-src="800x400.jpg" data-min-width="600"></span>
  <span data-src="1000x500.jpg" data-min-width="800"></span>
  <span data-src="1200x600.jpg" data-min-width="1000"></span>
</span>

4. Initialize the responsive image plugin.

$('.picture').responsiveImage();

5. Default settings.

$('.picture').responsiveImage({

  // The jQuery selector for source elements.
  source:             '> span',

  // A prefix for every(!) source element. 
  // Might be the default URL to the asset folder or a CDN so the source element only needs the relative path to the specific image.
  sourcePrefix:       '',

  // A default container element that defines the size for the responsive image to be loaded.
  // You can aslo pass the option via data-attribute, e.g. data-container="figure"
  container:          null,

  // These attributes are set to the generated responsive image tag. 
  attributes:         ['title', 'alt', 'class', 'width', 'height'],

  // Detect the resize of the viewport. 
  // You can set any event that can be used inside jQuery's .on() function.
  // Set resizeEvent to empty string to disable image calculation on resize.
  resizeEvent:       'resize',

  // Preload images before loading them into the DOM.
  preload:            false,

  // Automatically include dpr on best fit width calculation.
  autoDpr:            false,

  // The viewport and the container width are calculated automatically. 
  // The callback function can be used for any custom width calculation. 
  // Inside this function you can use the plugins' context.
  onGetWidth:         null,

  // The minimum width that is used, if no data-min-width was set.
  minWidthDefault:    0,

  // The maximum width that is used, if no data-max-width was set. 
  maxWidthDefault:    Number.MAX_VALUE,

  // The minimum device pixel ratio that is used if no data-min-dpr was set. 
  // If you want to show only Retina images set this value to 2
  minDprDefault:      1

  // The viewport and the container width are calculated automatically.
  // The callback function can be used for any custom width calculation. 
  // Inside this function you can use the plugins' context.
  onGetWidth:         null,

  // This callback function can be used to completely overwrite the source loading process.
  onLoadSources:      null

});

6. Events.

• ready.responsiveImage: fires when the responsive image was initially loaded, fires only once  
• all.ready.responsiveImage: fires when all responsive images were initially loaded, fires only once
• new.source.responsiveImage: fires when the image was inserted into the DOM
• load.source.responsiveImage: fires when the image source was loaded

Changelog:

v1.6.0 (2018-09-18)

• added image load error handling and documented optional <img> tag as fallback

v1.5.0 (2017-12-03)

• added load.responsiveImage event listener

v1.4.3 (2017-09-26)

• removed off() from image load

v1.4.1 (2016-04-06)

• fixed min-dpr result to 1 because of lower dpr values on zoomed sites

v1.4.0 (2016-02-10)

• added sourcePrefix option

v1.3.1 (2016-02-01)

• added option to disable resize event

2015-12-10

• added events for ready, all.ready
• added load event to newly created image

2015-07-06

• refactored attribute injection to be configurable

---

This awesome jQuery plugin is developed by janrembold. For more Advanced Usages, please check the demo page or visit the official website.