Responsive Image Lazy Load JS Library – lazysizes

Category: Javascript , Loading , Recommended | March 27, 2021
Author: aFarkas
Views Total: 124 views
Official Page: Go to website
Last Update: March 27, 2021
License: MIT


Responsive Image Lazy Load JS Library – lazysizes


lazysizes is an easy yet robust JS library used to delay the loading of images (iframes, scripts, etc) until they come into view, as well as loading the appropriate sources according to the breakpoints defined in the markup to fit any screen size.

Designed for high-performance websites to improve the page load time and to save the bandwidth.

Basic Usage:

1. Load the lazysizes.min.js script in your document.

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

2. Load the lazysizes’ plugins if needed.

// Allows you to fully control art direction through your CSS.
// This is accomplished by two techniques which you can be used separately or combined.
// The extension hooks into the data-sizes="auto" feature.
<script src="plugins/ls.artdirect.min.js"></script>

// Helps pre-occupy the space needed for an image by calculating the height from the image width or the width from the height.
// This means the width or height has to be calculable before the image is loaded
// This can serve as an alternative to the different CSS intrinsic ratio patterns.
<script src="plugins/ls.aspectratio.min.js"></script>

// Allows you to change the default data attributes.
// It automatically detects changes to your data-* attributes and adds the class for you.
<script src="plugins/ls.attrchange.min.js"></script>

// Allows you to define multiple background images with a width descriptor
// Similar to how img[srcset] works as also art directed images using media queries, similar to how picture works.
// The extension will then load the best image size for the current viewport and device.
// In case the browser does not support responsive images natively either picturefill or the respimg polyfill plugin has to be used.
<script src="plugins/ls.bgset.min.js"></script>

// Lazyload the low quality placeholder and enables you to create a blur up/fade over effect
<script src="plugins/ls.blur-up.min.js"></script>

// Allows you to automatically sync and manage your breakpoints between your CSS
// and the media attributes of your "picture > source" elements using the customMedia option of lazySizes.
<script src="plugins/ls.custommedia.min.js.js"></script>

// Fixes the missing h descriptor parsing in MS Edge by removing
// the h from all candidates of source and img elements and storing
// the physical aspect ratio of the candidates into a data-aspectratio attribute.
<script src="plugins/ls.fix-edge-h-descriptor.min.js"></script>

// Includes HTML content
<script src="plugins/ls.include.min.js"></script>

// Automatically transforms img.lazyload/iframe.lazyload elements in browsers that support native lazy loading
<script src="plugins/ls.native-loading.min.js"></script>

// Allows you to transform any HTML inside a noscript element as soon as it becomes visible.
<script src="plugins/ls.noscript.min.js"></script>

// Polyfills object-fit: cover and contain properties as also the object-position in non supporting browser.
<script src="plugins/ls.object-fit.min.js"></script>

// Helps you to limit/constrain the maximum resolution in case the w descriptor is used.
// Simply add the attribute data-optimumx="1.6" to constrain the max resolution to 1.6
<script src="plugins/ls.optimumx.min.js"></script>

// Extends the data-sizes="auto" feature to also calculate the right sizes for
// object-fit: contain|cover image elements as also height ( and width) constrained image elements in general.
<script src="plugins/ls.parent-fit.min.js"></script>

// Automatically unveils all element as soon as a print is detected even if the given lazyload image isn't in the viewport.
<script src="plugins/ls.print.min.js"></script>

// Optimizes perceived performance by adding better support for
// rendering progressive JPGs/PNGs in conjunction with the LQIP pattern.
<script src="plugins/"></script>

// Polyfill for responsive image
<script src="plugins/ls.respimg.min.js"></script>

// Enables lazySizes to generate the best suitable image source based on an URL pattern.
// It works with pre-build images (i.e. grunt-responsive-images) as also with any third party
// (ReSrc, Pixtulate, mobify, WURFL's Image Tailor ...)
// or self hosted restful responsive image services (responsive image on demand).
<script src="plugins/ls.rias.min.js"></script>

// Fixes Firefox issue
<script src="plugins/ls.static-gecko-picture.min.js"></script>

// Unloads img.lazyload (including picture) elements if they consume a lot of memory and they are out of view.
// To improve memory consumption as also resize/orientationchange performance.
<script src="plugins/ls.unload.min.js"></script>

// Extends lazySizes to also unveil / lazyload scripts/widgets, background images, styles and video/audio elements
<script src="plugins/ls.unveilhooks.min.js"></script>

3. Insert a low quality image with the essential CSS class ‘lazyload’ into your document. Use Html5 data-src attribute to specify the normal/high quality image source.

<img src="low-quality-src.jpg" data-src="normal-quality-src.jpg" class="lazyload">

4. Integration with the respimage.js plugin.

    data-srcset="image1.jpg 100w,
    image2.jpg 300w,
    image3.jpg 600w,
    image4.jpg 900w" class="lazyload">

5. Done. The JS library will take care of the rest.

6. All possible options.


  // default classes and attributes
  lazyClass: 'lazyload',
  loadedClass: 'lazyloaded',
  loadingClass: 'lazyloading',
  preloadClass: 'lazypreload',
  errorClass: 'lazyerror',
  autosizesClass: 'lazyautosizes',
  fastLoadedClass: 'ls-is-cached',
  srcAttr: 'data-src',
  srcsetAttr: 'data-srcset',
  sizesAttr: 'data-sizes',

  // The iframeLoadMode can be used to determine how iframes are lazyloaded. 
  // Possible values are 0 = Use location.replace()
  // 1 = Change src attribute. 
  // 0 is recommended for most users unless external dependencies require the presence of a src attribute (e.g. native video tracking in Google Tag Manager/Analytics).
  iframeLoadMode: 0,
  // if the image size is below 40
  // lazysizes traverses up the DOM tree until it finds a parent which is over 40 and uses this number
  minSize: 40,

  // an alias map for different media queries
  customMedia: {},

  // auto init on page load
  init: true,

  // calculates the "preload expand", by multiplying the normal expand with the expFactor 
  // which is used to preload assets while the browser is idling (no important network traffic and no scrolling)
  // Reasonable values are between 1.5 and 4 depending on the expand option
  expFactor: 1.5,

  // modifies the horizontal expand by multiplying the expand value with the hFac value. 
  // Use case: In case of carousels there is often the wish to make the horizontal expand 
  // narrower than the normal vertical expand option. 
  // Reasonable values are between 0.4 - 1. 
  // In the unlikely case of a horizontal scrolling website also 1 - 1.5.
  hFac: 0.8,

  // 0 = don't load anything
  // 1 = only load visible elements
  // 2 = load also very near view elements
  // 3 = load also not so near view elements
  loadMode: 2,

  // whether to load visibility: hidden elements.
  loadHidden: true,

  // the timeout option used for the requestIdleCallback
  ricTimeout: 0,

  // the timeout option used to throttle all listeners
  throttleDelay: 125

For more advanced usages, check out the in the zip.


v5.3.1 (2021-03-27)

  • Added basic Typescript support

v5.3.0 (2021-01-03)

  • BGSet: Support adding multiple images/backgrounds through event.detail.fullSrc
  • RiaS plugin: Use source based config in case of picture element usage
  • BlurUp plugin: Added possibility to change classNames
  • Core: Added iframeLoadMode option

v5.2.2 (2020-05-27)

  • Updated plugins

v5.2.1 (2020-05-26)

  • BlurUp-Plugin: Copy style attribute
  • Fixes minor security issue with video-embed plugin
  • Built: Update dependencies
  • Fixes diverse issues with old AMD module pattern

v5.2.0 (2019-12-18)

  • Update and bugfix

You Might Be Interested In:

Leave a Reply