lazysizes - the umltimate lazyloader for responsive images, iframes and widget

# lazySizes

lazySizes is the ultimate and lightweight lazyLoader which lazy loads images (including responsive images (picture/srcset)), iframes and scripts. It is written in VanillaJS and with high performance in mind.

Simply add the JS to your website and put the `class` `lazyload` to all elements, which should be lazy loaded. For a short API description go to the readme.md.

### Image with LQIP technique

The low quality image placeholder pattern is a performance technique. While it might increase measured time until the `onload` event, it dramatically increases perceived performance.

This pattern is recommended for above the fold/critical images.

    <img
    	alt="100%x200"
    	src="low-quality.jpg"
    	data-src="normal-quality.jpg"
    	class="lazyload" />

### Normal lazy image

The normal image pattern can be used for non-critical/below the fold images or in case there is no low quality image available:

    <img class="lazyload" data-src="image.jpg" alt="Desert Road" />

### responsive image with srcset and sizes attribute

Simply use `data-srcset` and `data-sizes` and you can support responsive images.

    <img
    	alt=""
    	src="small.jpg"
    	sizes="(min-width: 1000px) 930px, 90vw"
    	data-srcset="small.jpg 500w,
    		medium.jpg 640w,
    		big.jpg 1024w"
    	class="lazyload" />

### responsive image with the `picture` element

The picture element is also supported. Simply add the `lazyload` class to the `img` and use `data-srcset` on your `source` and the `img` element.

    <picture>
    	<!--[if IE 9]><video style="display: none"><![endif]-->
    	<source
    		data-srcset="500.jpg"
    		media="(max-width: 500px)" />
    	<source
    			data-srcset="1024.jpg"
    			media="(max-width: 1024px)" />
    	<source
    			data-srcset="1200.jpg" />
    <!--[if IE 9]></video><![endif]-->
    <img
    		src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
    		class="lazyload"
    		data-src="1024.jpg"
    		alt="image with artdirection" />
    </picture>

automatic sizes feature: In case of lazy loading images the `sizes` attribute of the `img`/`source` elements can be calculated with JS.

This automatic sizes feature is directly included in lazySizes. Simply use the keyword `auto` inside of the `data-sizes` attributes (`data-sizes="auto"`).

Important: How `sizes` is calculated: The automatic sizes calculation takes the width of the image if it is over `40` (see also `minSize` option). In case it's below the `minSize` threshold, it traverses up the DOM tree until it finds a parent which is over `40` and uses this number. Often the following general CSS rule might help: `img[data-sizes="auto"] { display: block; }`.

### responsive image with srcset and automatic sizes attribute

The autosizes feature makes using responsive images with the right `sizes` value easy as hell.

    <img
    	alt=""
    	data-sizes="auto"
    	data-src="medium.jpg"
    	data-srcset="small.jpg 500w,
    		medium.jpg 640w,
    		big.jpg 1024w"
    	class="lazyload" />

For responsive images support you must use either use a full polyfill like picturefill or use the extreme lightweight partial respimg polyfill plugin or use the Responsive Images as a Service extension.

### iframe

Iframes can be loaded too:

    <iframe data-src="//www.youtube.com/embed/ZfV-aYdU4uE" class="lazyload" frameborder="0" allowfullscreen></iframe>

### `[data-expand]`: More than lazyloading

LazySizes normally loads in view elements as fast as possible and near the view elements are lazily pre-loaded. This can be modified in general using the `expand` option. With the `data-expand` attribute this can be changed element specific to expand or shrink the viewport.

This can be used to create unveiling effects for elements with or even without loading anything.

    <style>
    .teaser.lazyload {
    	opacity: 0;
    	transform: scale(0.8);
    }

    .teaser.lazyloaded {
    	opacity: 1;
    	transform: scale(1);
    	transition: all 700ms;
    }
    </style>

    <script>

    window.lazySizesConfig = {
    	addClasses: true
    };
    </script>

    <div class="teaser lazyload" data-expand="-80">
    	<img data-src="image.jpg" class="lazyload" />
    	<h1>Teaser Title</h1>
    	<p>...</p>
    </div>

### First slide label

Nulla vitae elit libero, a pharetra augue mollis interdum.

### Third slide label

Praesent commodo cursus magna, vel scelerisque nisl consectetur.

### Widgets/Javascript/Script

LazySizes can be extended to load nearly everything lazily. The ls.unveilhooks.js plugin can be used to lazy load scripts, background images, and videos. Simply add a `data-script` to your widget and you are done:

    <div data-ride="carousel" data-script="assets/js/bootstrap.min.js" class="carousel lazyload">
    	<!-- widget content -->
    <div>

While other lazy loaders or responsive images solution need to be called, if new elements are added to the DOM or do become visible through a special user interaction or a JavaScript behavior.

LazySizes does automatically detect any changes to the DOM and the visibility of `.lazyload` elements.