# lozad
> A light-weight JS library to lazy load any HTML element such as images, ads, videos etc.
Latest version **1.16.0** (published 2020-09-06) · MIT license · 0 weekly downloads
## Install
```sh
npm install lozad
pnpm add lozad
yarn add lozad
bun add lozad
```
## Health
**Score 38/100 (D)** — status: abandoned.
Positive: has types package; esm support; no vulnerabilities; high quality score.
Warnings: low downloads.
Negative: abandoned.
## Facts
| | |
|---|---|
| Version | 1.16.0 |
| Published | 2020-09-06 |
| First published | 2017-08-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/lozad) |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 28.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7492 |
| Author | Apoorv Saxena |
| Maintainers | apoorvsaxena |
| Keywords | lazy, loader, lazyloader, lazyload, performance, image, video, iframe, ads |
## Links
- npm: https://www.npmjs.com/package/lozad
- Repository: https://github.com/ApoorvSaxena/lozad.js
- Issues: https://github.com/ApoorvSaxena/lozad.js/issues
- npm.io page: https://npm.io/package/lozad
## Alternatives
- [csv-to-markdown-table](https://npm.io/package/csv-to-markdown-table.md) — 47.0K weekly downloads
- [@sapphire/ratelimits](https://npm.io/package/@sapphire/ratelimits.md) — 4.4K weekly downloads
- [js-csvparser](https://npm.io/package/js-csvparser.md) — 2.0K weekly downloads
- [@adadapted/js-sdk](https://npm.io/package/@adadapted/js-sdk.md) — 251 weekly downloads
- [@grapecity/spread-sheets-sparklines](https://npm.io/package/@grapecity/spread-sheets-sparklines.md) — 103 weekly downloads
## Recent versions
- 1.16.0 (latest) — 2020-09-06
- 1.15.0 — 2020-05-23
- 1.14.0 — 2019-10-19
- 1.9.0 — 2019-02-09
- 1.8.0 — 2019-01-31
- 1.7.0 — 2018-11-08
- 1.6.0 — 2018-07-24
- 1.5.0 — 2018-07-16
- 1.4.0 — 2018-04-21
- 1.3.0 — 2018-02-16
- 1.2.0 — 2018-01-23
- 1.1.0 — 2018-01-18
- 1.0.9 — 2017-10-25
- 1.0.8 — 2017-10-13
- 1.0.7 — 2017-10-13
- … 9 more at https://npm.io/package/lozad/versions
## README
# Lozad.js [](https://badge.fury.io/js/lozad) [](https://travis-ci.org/ApoorvSaxena/lozad.js) [](https://www.npmjs.com/package/lozad) [](https://www.jsdelivr.com/package/npm/lozad)
> Highly performant, light and configurable lazy loader in pure JS with no dependencies for images, iframes and more, using IntersectionObserver API
**Lozad.js**:
- lazy loads elements performantly using pure JavaScript,
- is a light-weight library, just [](https://cdn.jsdelivr.net/npm/lozad) minified & gzipped,
- has NO DEPENDENCIES :)
- allows lazy loading of dynamically added elements as well,
- supports <img>, <picture>, iframes, videos, audios, responsive images, background images and multiple background images etc.
- even supports LQIP (Low Quality Image Placeholder)
- is completely free and open source.
It is written with an aim to lazy load images, iframes, ads, videos or any other element using the recently added [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) with tremendous performance benefits.
## Featured in:
- [Web | Google Developers](https://developers.google.com/web/fundamentals/performance/lazy-loading-guidance/images-and-video/)
- [Product Hunt](https://www.producthunt.com/posts/lozad-js)
- [Reddit](https://www.reddit.com/r/webdev/comments/6zg1x0/highly_performant_light_05kb_and_configurable/)
- [CSS Tricks](https://css-tricks.com/lozad-js-performant-lazy-loading-images)
- [David Walsh](https://twitter.com/davidwalshblog/status/915319510646829061)
- [Codrops](https://twitter.com/Apoorv_Saxena/status/906586828265758720)
- [SitePoint](https://www.sitepoint.com/five-techniques-lazy-load-images-website-performance/)
## Brands using Lozad.js:
  
 
  
 
  
and many more...
## Table of Contents
- [Demo](https://apoorv.pro/lozad.js/demo/)
- [Background](#yet-another-lazy-loading-javascript-library-why)
- [Install](#install)
- [Usage](#usage)
- [Example with picture tag](#example-with-picture-tag)
- [Browser Support](#browser-support)
- [FAQs](#faqs)
- [Contribute](#contribute)
- [Changelog](#changelog)
- [License](#license)
## Yet another Lazy Loading JavaScript library, why?
Existing lazy loading libraries hook up to the scroll event or use a periodic timer and call `getBoundingClientRect()` on elements that need to be lazy loaded. This approach, however, is painfully slow as each call to `getBoundingClientRect()` forces the browser to re-layout the entire page and will introduce considerable jank to your website.
Making this more efficient and performant is what [IntersectionObserver](https://developers.google.com/web/updates/2016/04/intersectionobserver) is designed for, and it’s landed in Chrome 51. IntersectionObservers let you know when an observed element enters or exits the browser’s viewport.
## Install
```sh
# You can install lozad with npm
$ npm install --save lozad
# Alternatively you can use Yarn
$ yarn add lozad
# Another option is to use Bower
$ bower install lozad
```
Then with a module bundler like rollup or webpack, use as you would anything else:
```javascript
// using ES6 modules
import lozad from 'lozad'
// using CommonJS modules
var lozad = require('lozad')
```
Or load via **CDN** and include in the `head` tag of your page.
```html
```
When loading from CDN, you can find the library on `window.lozad`.
---
## Usage
In HTML, add an identifier to the element (default selector identified is `lozad` class):
```html
```
All you need to do now is just instantiate Lozad as follows:
```js
const observer = lozad(); // lazy loads elements with default selector as '.lozad'
observer.observe();
```
or with a DOM `Element` reference:
```js
const el = document.querySelector('img');
const observer = lozad(el); // passing a `NodeList` (e.g. `document.querySelectorAll()`) is also valid
observer.observe();
```
or with custom options:
```js
const observer = lozad('.lozad', {
rootMargin: '10px 0px', // syntax similar to that of CSS Margin
threshold: 0.1 // ratio of element convergence
});
observer.observe();
```
Reference:
- [IntersectionObserver options: rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)
- [IntersectionObserver options: thresholds](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/thresholds)
or if you want to give custom function definition to load element:
```js
lozad('.lozad', {
load: function(el) {
console.log('loading element');
// Custom implementation to load an element
// e.g. el.src = el.getAttribute('data-src');
}
});
```
If you would like to extend the `loaded` state of elements, you can add the loaded option:
> **Note**: The `"data-loaded"="true"` attribute is used by lozad to determine if an element has been previously loaded.
```js
lozad('.lozad', {
loaded: function(el) {
// Custom implementation on a loaded element
el.classList.add('loaded');
}
});
```
If you want to lazy load dynamically added elements:
```js
const observer = lozad();
observer.observe();
// ... code to dynamically add elements
observer.observe(); // observes newly added elements as well
```
for use with responsive images
```html
```
for use with background images
```html
```
for use with multiple background images
```html
```
for use with responsive background images (image-set)
```html
```
To change the delimiter that splits background images:
```html
```
If you want to load the images before they appear:
```js
const observer = lozad();
observer.observe();
const coolImage = document.querySelector('.image-to-load-first')
// ... trigger the load of a image before it appears on the viewport
observer.triggerLoad(coolImage);
```
### Large image improvment
Sometimes image loading takes a long time. For this case, you can add a placeholder background:
```html
```
Lozad sets a placeholder background color of img element and users will see the fallback till the image loads.
## Example with picture tag
Create _a broken_ picture element structure.
> IE browser don't support picture tag!
> You need to set `data-iesrc` attribute (only for your picture tags) with source for IE browser
> `data-alt` attribute can be added to picture tag for use in `alt` attribute of lazy-loaded images
```html
```
When _lozad_ loads this picture element, it will fix it.
If you want to use image placeholder (like low quality image placeholder), you can set a temporary `img` tag inside your `picture` tag. It will be removed when _lozad_ loads the picture element.
```html
```
## Example with video
```html
```
## Example with iframe
```html
```
That's all, just add the `lozad` class.
## Example toggling class
```html
```
All you need to do now is just instantiate Lozad as follows:
```js
const observer = lozad(); // lazy loads elements with default selector as '.lozad'
observer.observe();
```
or with a DOM `Element` reference:
```js
const el = document.querySelector('img');
const observer = lozad(el); // passing a `NodeList` (e.g. `document.querySelectorAll()`) is also valid
observer.observe();
```
or with custom options:
```js
const observer = lozad('.lozad', {
rootMargin: '10px 0px', // syntax similar to that of CSS Margin
threshold: 0.1 // ratio of element convergence
});
observer.observe();
```
Reference:
- [IntersectionObserver options: rootMargin](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)
- [IntersectionObserver options: thresholds](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/thresholds)
or if you want to give custom function definition to load element:
```js
lozad('.lozad', {
load: function(el) {
console.log('loading element');
// Custom implementation to load an element
// e.g. el.src = el.getAttribute('data-src');
}
});
```
If you would like to extend the `loaded` state of elements, you can add the loaded option:
> **Note**: The `"data-loaded"="true"` attribute is used by lozad to determine if an element has been previously loaded.
```js
lozad('.lozad', {
loaded: function(el) {
// Custom implementation on a loaded element
el.classList.add('loaded');
}
});
```
If you want to lazy load dynamically added elements:
```js
const observer = lozad();
observer.observe();
// ... code to dynamically add elements
observer.observe(); // observes newly added elements as well
```
for use with responsive images
```html