vanilla-lazyload - npm Package Compare versions

LazyLoad is a fast, lightweight and flexible script that _speeds up your web application_ by **loading your content images, video, iframes as they enter the viewport**. It's written in plain "vanilla" JavaScript, it uses the [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) API, and it supports [responsive images](https://alistapart.com/article/responsive-images-in-practice). It's also SEO-friendly and it has some other [notable features](#-notable-features).

➡️ Jump to: [👨‍💻 Getting started](#-getting-started) - [🥧 Recipes](#-recipes) - [📺 Demos](#-demos) - [😋 Tips & tricks](#-tips--tricks) - [🔌 API](#-api) - [😯 Notable features](#-notable-features)

➡️ Jump to: [👨‍💻 Getting started - HTML](#-getting-started---html) - [👩‍💻 Getting started - Script](#-getting-started---script) - [🥧 Recipes](#-recipes) - [📺 Demos](#-demos) - [😋 Tips & tricks](#-tips--tricks) - [🔌 API](#-api) - [😯 Notable features](#-notable-features)

---

## 👨‍💻 Getting started

## 👨‍💻 Getting started - HTML

### HTML markup

In order to make your content be loaded by LazyLoad, you must use some `data-` attributes instead of the actual attributes. Examples below.

@@ -108,7 +106,7 @@

### Include LazyLoad in your project

## 👩‍💻 Getting started - Script

The latest, recommended version of LazyLoad is **11.0.3**, which leverages the power and speed of the browser's **IntersectionObserver** API.

The latest, recommended version of LazyLoad is **11.0.4**, which leverages the power and speed of the browser's **IntersectionObserver** API.

#### IntersectionObserver: to polyfill or not to polyfill?

### To polyfill or not to polyfill IntersectionObserver?

@@ -121,3 +119,3 @@ On browser NOT supporting IntersectionObserver such as Internet explorer and older versions of Safari **you can choose whether or not to add a javascript polyfill** for it.

#### The simplest way

### The simple, easiest way

@@ -127,3 +125,3 @@ The easiest way to use LazyLoad is to include the script from a CDN:

```html

```

@@ -135,3 +133,3 @@

```

@@ -171,3 +169,3 @@

```js

var lazyLoadAmdUrl = "https://cdn.jsdelivr.net/npm/vanilla-lazyload@11.0.3/dist/lazyload.amd.min.js";

var lazyLoadAmdUrl = "https://cdn.jsdelivr.net/npm/vanilla-lazyload@11.0.4/dist/lazyload.amd.min.js";

var polyfillAmdUrl = "https://cdn.jsdelivr.net/npm/intersection-observer-amd@1.0.0/intersection-observer-amd.js";

@@ -217,3 +215,3 @@

```html

```

@@ -244,3 +242,3 @@

```html

```

@@ -328,20 +326,27 @@

<!--

##### What about LazyLoad 8.x?

Version 8.x of LazyLoad still works and exists on npm, cdnjs and jsdelivr, and you still can load it conditionally (if you do that, like [in this demo](demos/conditional_loading.html), you may use versions `8.17.0`/`10.20.1` which have similar API), but doing so is being **deprecated**. The reason of is:

## 🥧 Recipes

- `IntersectionObserver` [support is very wide](https://caniuse.com/intersectionobserver) now, coming to Safari in the very next few days;

- Internet Explorer will soon disappear from our radars, in the meantime you can load the polyfill on it. Or not, since [even Microsoft is telling users not to use it anymore](https://www.zdnet.com/article/microsoft-security-chief-ie-is-not-a-browser-so-stop-using-it-as-your-default/);

- Version 8.x listens on the container's `scroll` event, while version 10.x uses `IntersectionObserver`, so they behave differently (e.g. with sliders, or with different scrolling containers).

This is the section where you can find _ready to copy & paste_ code for your convenience.

The [official w3c polyfill](https://github.com/w3c/IntersectionObserver/tree/master/polyfill) could be loaded _conditionally_ on less recent versions of Safari and Internet Explorer, using [Polyfill.io](https://cdn.polyfill.io/v3/).

-->

### Dynamic content

## 🥧 Recipes

> 💡 **Use case**: when you want to lazily load images, but the number of images change in the scrolling area changes, maybe because they are added asynchronously.

This is the section where you can find _copy & paste_ code for your convenience.

HTML

### Scrolling panel

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

Javascript

```js

var myLazyLoad = new LazyLoad();

// After your content has changed...

myLazyLoad.update();

```

[DEMO](https://verlok.github.io/lazyload/demos/dynamic_content.html) - [SOURCE](https://github.com/verlok/lazyload/blob/master/demos/dynamic_content.html) - [API](#-api)

### Scrolling panel(s)

> 💡 **Use case**: when your scrolling container is not the main browser window, but a scrolling container.

@@ -367,5 +372,4 @@

### Multiple scrolling panels

> 💡 **Use case**: when your scrolling container is not the main browser window, and you have multiple scrolling containers.

If you have _multiple_ scrolling panels, you can use the following markup and code.

@@ -396,5 +400,5 @@ HTML

### Delay load

### Delay loading

> 💡 **Use case**: you want the images to stay inside the viewport for some time before to start loading them, e.g. to skip loading some images them if the user scrolled fast after them.

> 💡 **Use case**: if a your scrolls fast over your images, you might wait a short time before the images start loading. This is how.

@@ -421,20 +425,2 @@ HTML

### Dynamic content

> 💡 **Use case**: 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

```js

var myLazyLoad = new LazyLoad();

// After your content has changed...

myLazyLoad.update();

```

[DEMO](https://verlok.github.io/lazyload/demos/dynamic_content.html) - [SOURCE](https://github.com/verlok/lazyload/blob/master/demos/dynamic_content.html) - [API](#-api)

### Lazy LazyLoad

@@ -490,4 +476,35 @@

The [demos](https://github.com/verlok/lazyload/tree/master/demos) folder contains 15 use cases of LazyLoad. You might find there what you're looking for.

The [demos](https://github.com/verlok/lazyload/tree/master/demos) folder contains 20+ use cases of LazyLoad. You might find there what you're looking for.

| --------- | ----------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------- |

| Content | Lazy responsive images with the `<picture>` tag and the `media` attribute (art direction) | [Code](demos/picture_media.html) | [Live](https://www.andreaverlicchi.eu/lazyload/demos/picture_media.html) |

| Content | Lazy responsive images with `srcset` and `sizes` (using `data-sizes`) | [Code](demos/image_srcset_lazy_sizes.html) | [Live](https://www.andreaverlicchi.eu/lazyload/demos/image_srcset_lazy_sizes.html) |

| Content | Lazy responsive images with `srcset` and `sizes` (using plain `sizes`) | [Code](demos/image_srcset_sizes.html) | [Live](https://www.andreaverlicchi.eu/lazyload/demos/image_srcset_sizes.html) |

| Content | Lazy WebP images with the `<picture>` tag and the `type` attribute for WebP | [Code](demos/picture_type_webp.html) | [Live](https://www.andreaverlicchi.eu/lazyload/demos/picture_type_webp.html) |

| Loading | Asynchronous loading LazyLoad + InterserctionObserver with requireJS | [Code](demos/amd_polyfill.html) | [Live](https://www.andreaverlicchi.eu/lazyload/demos/amd_polyfill.html) |

| Technique | A popup layer containing lazy images in a scrolling container | [Code](demos/popup_layer.html) | [Live](https://www.andreaverlicchi.eu/lazyload/demos/popup_layer.html) |

| Methods | Adding dynamic content, then `update()` LazyLoad passing a NodeSet of elements | [Code](demos/dynamic_content_nodeset.html) | [Live](https://www.andreaverlicchi.eu/lazyload/demos/dynamic_content_nodeset.html) |

| (legacy) | Conditional loading of v.8 or v.10 (no IntersectionObserver polyfill) | [Code](demos/conditional_loading.html) | [Live](https://www.andreaverlicchi.eu/lazyload/demos/conditional_loading.html) |

---

@@ -622,23 +639,23 @@

| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------- |

| `threshold` | A number of pixels representing the outer distance off the scrolling area from which to start loading the elements. | `300` | `0` |

| `thresholds` | Similar to `threshold`, but accepting multiple values and both `px` and `%` units. It maps directly to the `rootMargin` property of `IntersectionObserver` ([read more](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)), so it must be a string with a syntax similar to the CSS `margin` property. You can use it when you need to have different thresholds for the scrolling area. It overrides `threshold` when passed. | `null` | `"500px 10%"` |

| `data_src` | The name of the data attribute containing the original image source, excluding the `"data-"` part. E.g. if your data attribute is named `"data-src"`, just pass `"src"` | `"src"` | `"original"` |

| `data_srcset` | The name of the data attribute containing the original image source set in either `img` and `source` tags, excluding the `"data-"` part. E.g. if your data attribute is named `"data-srcset"`, just pass `"srcset"` | `"srcset"` | `"original-set"` |

| `data_sizes` | The name of the data attribute containing the sizes attribute to use, excluding the `"data-"` part. E.g. if your data attribute is named `"data-sizes"`, just pass `"sizes"` | `"sizes"` | `null` |

| `data_bg` | The name of the data attribute containing the value of `background-image` to load lazily, excluding the `"data-"` part. E.g. if your data attribute is named `"data-bg"`, just pass `"bg"`. The attribute value must be a valid value for `background-image`, including the `url()` part of the CSS instruction. | `"bg"` | `"url(img1.jpg), url(img2.jpg)"` |

| `load_delay` | The time (in milliseconds) each image needs to stay inside the viewport before its loading begins. | `0` | `300` |

| `callback_enter` | A callback function which is called when an element enters the viewport. | `null` | `(el)=>{console.log("Entered", el)}` |

| `callback_exit` | A callback function which is called when an element exits the viewport. | `null` | `(el)=>{console.log("Exited", el)}` |

| `callback_reveal` | A callback function which is called when an element is activated (usually when it starts loading). | `null` | `(el)=>{console.log("Loading", el)}` |

| `callback_loaded` | A callback function which is called when an element was loaded. | `null` | `(el)=>{console.log("Loaded", el)}` |

| `callback_error` | A callback function which is called when an element triggered an error. | `null` | `(el)=>{console.log("Error", el)}` |

| `callback_finish` | A callback function which is called when there are no more elements to load and all elements have been downloaded. | `null` | `()=>{console.log("Finish")}` |

| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | ---------------------------------------- |

| `threshold` | A number of pixels representing the outer distance off the scrolling area from which to start loading the elements. | `300` | `0` |

| `thresholds` | Similar to `threshold`, but accepting multiple values and both `px` and `%` units. It maps directly to the `rootMargin` property of IntersectionObserver ([read more](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)), so it must be a string with a syntax similar to the CSS `margin` property. You can use it when you need to have different thresholds for the scrolling area. It overrides `threshold` when passed. | `null` | `"500px 10%"` |