Skip to content

Latest commit

 

History

History
408 lines (283 loc) · 14.6 KB

README.md

File metadata and controls

408 lines (283 loc) · 14.6 KB
Raw

LazyLoad is a fast, lightweight and flexible script that speeds up your web application by loading images only as they enter the viewport. LazyLoad supports responsive images, it's SEO friendly and it has some others notable features.

Jump to:

Include the script | Recipes | Tips & tricks | API | Notable features

Include the script

From cdnjs

Just include the latest version script, e.g. like that:

<script src="https://cdnjs.cloudflare.com/ajax/libs/vanilla-lazyload/7.2.0/lazyload.transpiled.min.js"></script>

Local install

If you prefer to install LazyLoad locally in your project, you can either:

  • download it from the dist folder. The file you typically want to use is lazyload.transpiled.min.js.
  • install it with npm install --save vanilla-lazyload
  • install it with bower install vanilla-lazyload.

Async script

It's possible to include it as an async script, see Recipes below.

Recipes

Simple

When to use: your lazy images are (normally) located in the body of a scrolling page.

HTML

<img alt="..." 
     data-original="../img/44721746JJ_15_a.jpg"
     width="220" height="280">

Javascript

var myLazyLoad = new LazyLoad();

DEMO | SOURCE | API

Responsive images - srcset and sizes

When to use: you want to lazily load responsive images using the srcset and the sizes attribute.

HTML

<img data-original="/your/image1.jpg"
    data-original-set="/your/image1.jpg 200w, /your/[email protected] 400w"
    sizes="(min-width: 20em) 35vw, 100vw">

Javascript

var myLazyLoad = new LazyLoad();

DEMO | SOURCE | API

Responsive images - picture

When to use: you want to lazily load responsive images using the picture tag.

HTML

<picture>
    <source media="(min-width: 1024px)" data-original-set="/your/image1a.jpg" />
    <source media="(min-width: 500px)" data-original-set="/your/image1b.jpg" />
    <img alt="Stivaletti" data-original="/your/image1.jpg">
</picture>

Javascript

var myLazyLoad = new LazyLoad();

DEMO | SOURCE | API

Async script + auto initialization

When to use: you want to use a non-blocking script (which is faster), and you don't need to have control on the exact moment when LazyLoad is created.

Include the following scripts at the end of your HTML page, right before closing the body tag.

HTML + Javascript

<script>
window.lazyLoadOptions = {
    /* your lazyload options */
};
</script>

<!-- Download the script and execute it after lazyLoadOptions is defined -->
<script async src="https://.../lazyload.transpiled.min.js"></script>

If you need multiple async instances, just pass window.lazyLoadOptions an array of settings.

<script>
window.lazyLoadOptions = [{
    /* your instance 1 options */
}, {
    /* your instance 2 options */
}];
</script>

<!-- Download the script and execute it after lazyLoadOptions is defined -->
<script async src="https://.../lazyload.transpiled.min.js"></script>

Please note that if you put the script at the beginning of your HTML page, LazyLoad will be sometimes executed before the browser has loaded all the DOM. In that case, you need to store the instance in a variable and use the update method on it. This will make it check the DOM again. See API.

DEMO | SOURCE | API

Auto init + store the instance in a variable

When to use: you want to use a non-blocking script (which is faster), you don't need to have control on the exact moment when LazyLoad is created, but you need to assign the an auto-initialized instance to a variable, e.g. to use the API on it.

HTML + Javascript

<script>
// Listen to the Initialized event
window.addEventListener('LazyLoad::Initialized', function (e) {
    // Get the instance and puts it in the lazyLoadInstance variable
    lazyLoadInstance = e.detail.instance;
}, false);

// Set the lazyload options for async usage
lazyLoadOptions = {
    /* your lazyload options */
};
</script>

<!-- Download the script and execute it after lazyLoadOptions is defined -->
<script async src="https://.../lazyload.transpiled.min.js"></script>

You will then have the auto-generated instance in the lazyLoadInstance variable.

DEMO | SOURCE | API

Scolling panel

When to use: when your scrolling container is not the main browser window, but a scrolling container.

HTML

<div id="scrollingPanel">
    <img alt="Image description" 
         data-original="../img/44721746JJ_15_a.jpg" 
         width="220" height="280">
    <!-- More images -->
</div>

Javascript

var myLazyLoad = new LazyLoad({
    container: document.getElementById('scrollingPanel')
});

DEMO | SOURCE | API

Multiple scrolling panels

When to use: when your scrolling container is not the main browser window, and you have multiple scrolling containers.

HTML

<div id="scrollingPanel1">
    <img alt="Image description" 
         data-original="../img/44721746JJ_15_a.jpg" 
         width="220" height="280">
    <!-- More images -->
</div>
<div id="scrollingPanel2">
    <img alt="Image description" 
         data-original="../img/44721746JJ_15_a.jpg" 
         width="220" height="280">
    <!-- More images -->
</div>

Javascript

var myLazyLoad1 = new LazyLoad({
    container: document.getElementById('scrollingPanel1')
});
var myLazyLoad2 = new LazyLoad({
    container: document.getElementById('scrollingPanel2')
});

DEMO | SOURCE | API

Dynamic content

When to use: when you want to lazily load images, but the number of images change in the scrolling area changes, maybe because they are added asynchronously.

HTML

The HTML to use depends on your case, see other recipes' HTML

Javascript

var myLazyLoad = new LazyLoad();
// After your content has changed...
myLazyLoad.update();

DEMO | SOURCE | API

Lazy iframes

When to use: you want to lazily load iframes in your web page, maybe because you have many or just because you want to load only what your users actually want to see.

HTML

<iframe data-original="iframes/i01.html" frameborder="0"></iframe>

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: "iframe"
});

DEMO | SOURCE | API

Lazy background images

When to use: your images are set as CSS background images instead of real img, but you still want to lazily load them.

HTML

<div class="lazy" data-original="../img/44721746JJ_15_a.jpg"></div>

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: ".lazy"
});

That's it. Whenever the element selected by elements_selector is not an img or an iframe, LazyLoad puts the image found in the data-original attribute in the background-image of the element.

DEMO | SOURCE | API

Tips & tricks

Occupy vertical space and maintain ratio

You need to be sure that the images that are going to be lazy loaded occupy some vertical space (*), ideally the same space of the loaded images. Otherwise, all the images will be loaded at once.

In an elastic layout where images width change, you want to keep vertical space maintaining the images height, using a width/height ratio calculation.

.image-wrapper {
    width: 100%;
    height: 0;
    padding-bottom: 66.67%; /* You define this doing height / width * 100% */
    position: relative;
}
.image {
    width: 100%;
    /*height: auto;*/
    position: absolute;
}

More info in Sizing Fluid Image Containers with a Little CSS Padding Hack by Andy Shora.

There's also a useful SASS mixin to maintain aspect ratio on CSS tricks.

@mixin aspect-ratio($width, $height) {
  position: relative;
  &:before {
    display: block;
    content: "";
    width: 100%;
    padding-top: ($height / $width) * 100%;
  }
  > .content {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
  }
}

Show the images while they load

Images should be shown while they load, and not after, to give your users the best perceived performance. This is especially true if you use a progressive loading format like progressive JPEG.

In order to make your images visible as soon as LazyLoad sets the src/srcset attribute to it, you can either:

Do it like that via CSS:

/* Prevents img without src to appear */
img:not([src]) {
    visibility: hidden;
}

Or do it using the CSS classes set by LazyLoad when loading starts - see API.

API

Options

For every instance of LazyLoad you can pass in some options, to alter its default behaviour. Here's the list of the options.

Name Meaning Default value
container The scrolling container, and the container of the elements in the elements_selector option. window
elements_selector The selector of the image elements inside the container, as descendants of the element in the container option "img"
threshold The distance out of the viewport, expressed in pixel, before which to start loading the images 300
throttle The time that has to pass between one element parsing and the following, when fast scroll events occur 150
data_src The name of the dataset property containing the original image source. "original"
data_srcset The name of the dataset property containing the original image source set. If you also use the sizes attribute, put it directly in the img tag, as sizes gets ignored when the srcset attribute is missing. "original-set"
class_loading The class applied to the elements while the loading is in progress. "loading"
class_loaded The class applied to the elements when the loading is complete "loaded"
class_error The class applied to the elements when the element causes an error "error"
class_initial The class applied to the first batch elements to be loaded in the page "initial"
skip_invisible Specifies whether the script has to consider invisible images or not true
callback_load A function to be called when an element was loaded. null
callback_error A function to be called when an element triggers an error. null
callback_set A function to be called when the src of an image is set in the DOM. null
callback_processed A function to be called when an image was processed. null

Methods

You can call the following public methods on any instance of LazyLoad.

Method name Effect
update() Tells LazyLoad that new lazy images have arrived in the container, so it must start to manage them
destroy() Destroys the instance, unsetting instance variables and removing listeners.
handleScroll() A throttled scroll handler. This is called automatically from LazyLoad if the container element fires a scroll event, but it's exposed as a public method to allow you to use LazyLoad otherwise (i.g. when using iScroll)

Notable features

SEO friendly

LazyLoad doesn't hide your images from search engines, even if you don't specify any initial src you your image.

Progressive JPEG support --> improve perceived performance

Progressive JPEG is an image format which is very good for perceived performance because it's rendered sooner, and refined in progressive passes. LazyLoad shows your images while they load, letting progressive JPEG do its magic.

It works with your favourite framework

As LazyLoad doesn't rely on jQuery, you can use it in web applications using Angular, React or Vue.js without the need to include jQuery.

Support for responsive images.

LazyLoad supports responsive images, both via the srcset & sizes attributes and via the picture tag.

Throttled execution for optimized CPU usage

LazyLoad's listeners to the container's scroll and resize events are throttled by default, meaning that the main function of the script will not overload the CPU of devices with a smooth scroll.

Much faster than jQuery_lazyload

This script is comparable to the notorious jQuery_lazyload, but LazyLoad is 6x faster, because LazyLoad uses only optimized, native javascript functions and methods, instead of jQuery. Your users will see the difference, even in slow devices or computers.