Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/shinsenter/defer.js

🥇 A lightweight JavaScript library that helps you lazy load (almost) anything. Defer.js is dependency-free, highly efficient, and optimized for Web Vitals.
https://github.com/shinsenter/defer.js
deferjs intersection-observer lazy-audio lazy-css lazy-iframe lazy-image lazy-javascript lazy-js lazy-picture lazy-stylesheet lazy-video lazyload lazyloader lazysizes microjs scroll-reveal srcset unveil vanilla-lazyload vanillajs
Last synced: 4 days ago
JSON representation
🥇 A lightweight JavaScript library that helps you lazy load (almost) anything. Defer.js is dependency-free, highly efficient, and optimized for Web Vitals.
Host: GitHub
URL: https://github.com/shinsenter/defer.js
Owner: shinsenter
License: mit
Created: 2019-02-14T12:59:35.000Z (almost 6 years ago)
Default Branch: main
Last Pushed: 2024-07-14T12:32:55.000Z (4 months ago)
Last Synced: 2024-11-06T18:45:54.443Z (14 days ago)
Topics: deferjs, intersection-observer, lazy-audio, lazy-css, lazy-iframe, lazy-image, lazy-javascript, lazy-js, lazy-picture, lazy-stylesheet, lazy-video, lazyload, lazyloader, lazysizes, microjs, scroll-reveal, srcset, unveil, vanilla-lazyload, vanillajs
Language: JavaScript
Homepage: https://shinsenter.github.io/defer.js/
Size: 928 KB
Stars: 277
Watchers: 12
Forks: 44
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project

README

        # @shinsenter/defer.js

🥇 A lightweight JavaScript library that helps you lazy load (almost) anything. Defer.js is dependency-free, highly efficient, and optimized for Web Vitals.

[![NPM](https://img.shields.io/npm/l/@shinsenter/defer.js)](https://code.shin.company/defer.js/blob/master/LICENSE)

[![GitHub Release Date](https://img.shields.io/github/release-date/shinsenter/defer.js)](https://code.shin.company/defer.js/releases)

[![GitHub package.json version](https://img.shields.io/github/package-json/v/shinsenter/defer.js)](https://code.shin.company/defer.js/releases)

[![npm bundle size (scoped)](https://img.shields.io/bundlephobia/minzip/@shinsenter/defer.js)](https://www.npmjs.com/package/@shinsenter/defer.js)

[![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/@shinsenter/defer.js)](https://www.jsdelivr.com/package/npm/@shinsenter/defer.js)

> 💡 [View document in other languages](#documentation-in-other-languages)

## Introduction

Sluggish Big CSS files, slow JavaScript, or bulky media resources can negatively impact your website's Web Vitals, leading to a slow and frustrating user experience. But what if you could seamlessly defer these resources and boost your website's load speed?

By utilizing Defer.js, you can bid farewell to these issues! With its lazy loading capabilities, dependency-free design, lightning-fast performance, and hard-won experience, Defer.js is the ultimate solution for optimizing your website's Web Vitals. Whether you're using a modern or legacy browser, Defer.js makes it a breeze to enhance your website's user experience with blazing-fast loading times.

## Why Choose Defer.js

- 🧩 Effortlessly lazy load almost anything

- 🔰 Easy to use, even for beginners

- 🚀 Lightweight and blazingly fast, with no dependencies

- ⚡️ Super tiny (minzipped size is around 1KB)

- 🤝 Seamlessly integrates with your favorite frameworks

- 🦾 Optimized for the latest Web Vitals standards

- 📱 Optimized for use on smartphones

- ✅ Supports legacy browsers like Internet Explorer 9 ^{[(*)](#browser-support)}

## Contributing

[![NPM](https://nodei.co/npm/@shinsenter/defer.js.png?downloads=true)](https://www.npmjs.com/package/@shinsenter/defer.js)

- **Package**: [@shinsenter/defer.js](https://www.npmjs.com/package/@shinsenter/defer.js)

- **Version**: 3.8.0

- **Author**: Mai Nhut Tan 

- **Copyright**: 2019-2024 SHIN Company 

- **License**: [MIT](https://code.shin.company/defer.js/blob/master/LICENSE)

If you find the project useful, please give it a star or consider donating via [PayPal](https://www.paypal.me/shinsenter).

You can also [open a discussion](https://github.com/shinsenter/defer.js/discussions/new/choose) on Github if you have any idea to improve the library.

[![Donate via PayPal](https://img.shields.io/badge/Donate-Paypal-blue)](https://www.paypal.me/shinsenter) [![Become a Stargazer](https://img.shields.io/badge/Become-Stargazer-yellow)](https://code.shin.company/defer.js/stargazers) [![Report an issue](https://img.shields.io/badge/New-Discussions-green)](https://code.shin.company/defer.js/discussions/new/choose)

Your support helps maintain and improve these project for the community.

I appreciate you respecting my intellectual efforts in creating this library.

If you intend to copy or use ideas from this project, please give proper credit.

---

## Getting Started

Defer.js is an easy-to-use library that will help boost your website's performance by reducing loading times. Here's how to get started:

### Basic

Add the Defer.js library to your page by including a `` tag just below the opening `<head>` tag.

```html

<head>

  <meta charset="UTF-8" />

  <title>My Awesome Page</title>

  <!-- Add Defer.js here -->

  <script src="https://cdn.jsdelivr.net/npm/@shinsenter/[email protected]/dist/defer.min.js">

  

```

### Inlining the Library

To save an HTTP request, you can even inline the entire Defer.js library by copying its content from the [defer.min.js](https://cdn.jsdelivr.net/npm/@shinsenter/[email protected]/dist/defer.min.js) and replacing the comments in the script tag with its content.

```html

  

  My Awesome Page

  

  /* Defer.js content goes here */

  

```

### Compatibility with Older Versions

If you're using Defer.js v1.x, you can use `defer_plus.min.js` instead of `defer.min.js` without wondering about migrations.

```html

  

  My Awesome Page

  

  

  

```

### For OLD Browsers (such as IE9)

To enhance performance for legacy browsers that don't support the `IntersectionObserver` feature, you can load the IntersectionObserver polyfill library after the `defer.min.js` script tag.

```html

/* Defer.js content */

'IntersectionObserver'in window||document.write('<script src="https://cdn.jsdelivr.net/npm/@shinsenter/[email protected]/dist/polyfill.min.js"><\/script>');

```

*NOTE*: Modern browsers support the `IntersectionObserver` feature, so you don't have to worry about adding the polyfill if you don't have legacy browsers in mind.

---

## Functions

* [Defer(func, [delay], [waitForUserAction])](#Defer) ⇒ void

    * [.lazy](#Defer.lazy) : boolean \| number

    * [.all([selector], [delay], [waitForUserAction])](#Defer.all) ⇒ void

    * [.dom([selector], [delay], [unveiledClass], [resolver], [observeOptions])](#Defer.dom) ⇒ void

    * [.css(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction])](#Defer.css) ⇒ void

    * [.js(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction])](#Defer.js) ⇒ void

    * [.reveal(node, [unveiledClass])](#Defer.reveal) ⇒ void

* ~~[defer(func, [delay])](#defer)~~

* ~~[deferimg([selector], [delay], [unveiledClass], [resolver], [observeOptions])](#deferimg)~~

* ~~[deferiframe([selector], [delay], [unveiledClass], [resolver], [observeOptions])](#deferiframe)~~

* ~~[deferstyle(src, [id], [delay], [onload])](#deferstyle)~~

* ~~[deferscript(src, [id], [delay], [onload])](#deferscript)~~

## Typedefs

* [Node](#Node)

* [Function](#Function)

* [NodeHandler](#NodeHandler) ⇐ [Function](#Function)



## Defer(func, [delay], [waitForUserAction]) ⇒ void

Heavy DOM manipulations can cause render-blocking issues in real-world scenarios.

Wrapping your script with `Defer()` may help prevent render-blocking issues on your website.

**Kind**: global function  

**Since**: 2.0  

| Param | Type | Default | Description |

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

| func | function |  | A function to be executed after the page is fully loaded. |

| [delay] | number | 0 | A timespan, in milliseconds, that the page should wait before executing the function. |

| [waitForUserAction] | boolean \| number | false | This argument tells `Defer()` to delay execution and wait until there is a user interaction. |

**Example**  

This example uses jQuery to perform some DOM manipulations.

It will attach `
` blocks to the document

as soon as the page finishes loading.

```html

  function generate_code_blocks () {

    $('.demo').each(function() {

      var code = $('<pre><code class="language-html"></code></pre>');

      var demo = $(this);

      var html = demo.html().trim().replace(/ {4}/g, '  ');

      code.children().text(html);

      demo.append(code);

    });

  }

  Defer(generate_code_blocks, 0);

```

**Example**  

Sometimes, you may want your code to run only when there is user activity.

The third argument tells `Defer()` to delay executing the function

and wait until the user starts interacting with your page.

```html

  body.moving {

    background: linear-gradient(270deg, #c2fff5, #eec3f0, #a1c1ff);

    background-size: 600% 600%;

    animation: moving_bg 30s ease infinite;

  }

  function make_background_animate() {

    // jQuery is used in this example to attach a class to the <body> tag.

    // You won't see the animated background until you start interacting.

    $('body').addClass('moving');

  }

  Defer(make_background_animate, 0, true);

```

* [Defer(func, [delay], [waitForUserAction])](#Defer) ⇒ void

    * [.lazy](#Defer.lazy) : boolean \| number

    * [.all([selector], [delay], [waitForUserAction])](#Defer.all) ⇒ void

    * [.dom([selector], [delay], [unveiledClass], [resolver], [observeOptions])](#Defer.dom) ⇒ void

    * [.css(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction])](#Defer.css) ⇒ void

    * [.js(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction])](#Defer.js) ⇒ void

    * [.reveal(node, [unveiledClass])](#Defer.reveal) ⇒ void

* * *



### Defer.lazy : boolean \| number

The `Defer.lazy` variable was added since v3.0.

Setting `Defer.lazy=true` tells the library to delay executing

deferred scripts until the user starts interacting with the page,

regardless of the page load event.

Changing this variable will also affect the default value

of the `waitForUserAction` argument in these functions:

- [`Defer()`](#Defer)

- [`Defer.all()`](#Defer.all)

- [`Defer.css()`](#Defer.css)

- [`Defer.js()`](#Defer.js)

**Kind**: static property of [Defer](#Defer)  

**Default**: (not set)  

**Access**: public  

**Since**: 3.0  

**Example**  

To override the default behavior of the `Defer()` method:

```html

Defer.lazy = true;

```

**Example**  

You can set a timeout period in milliseconds for the `Defer.lazy`

variable or any `waitForUserAction` argument.

If no user interaction occurs within this timeout period, the scripts will still execute.

```html

Defer.lazy = 10000; // 10 seconds

```

This feature was added since v3.8.0.

View some use cases in [this discussion](https://github.com/shinsenter/defer.js/discussions/131#discussioncomment-8775870).

* * *



### Defer.all([selector], [delay], [waitForUserAction]) ⇒ void

Slow scripts (third-party libraries, add-ons, widgets, etc.)

may cause [Web Vitals](https://web.dev/vitals/) issues in real-world scenarios.

Fully deferring `` tags may help prevent Web Vitals issues on your page.

You can fully defer any script tag by setting its `type` attribute to `deferjs`.

This trick also works perfectly with `<script>` tags that have an `src` attribute.

**Kind**: static method of [<code>Defer</code>](#Defer)  

**Note**: (1) To avoid unexpected behavior when using

the `Defer.all()` method to delay executing script tags,

you should call the `Defer.all()` method with a regular script tag.  

**Note**: (2) Lazy loading behavior changed since v3.0

when you set `Defer.lazy=true` or `waitForUserAction=true`.

A `<script>` tag with `type="deferjs"` will not execute

unless the user starts interacting with your page.  

**Note**: (3) Since v3.8.0, you can set a timeout period in milliseconds

for the `Defer.lazy` variable or any `waitForUserAction` argument.

If no user interaction occurs within this timeout period, the scripts will still execute.

View some use cases in [this discussion](https://github.com/shinsenter/defer.js/discussions/131#discussioncomment-8775870).  

**Note**: (4) The [Resource hints](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload) feature was added since v3.2,

as it is recommended to prevent issues called "[Taming the Waterfall](https://blog.cloudflare.com/too-old-to-rocket-load-too-young-to-die/#quirksitamingthewaterfall)".

This feature is discussed in [#112](https://code.shin.company/defer.js/issues/112).  

**Note**: (5) Known Issue:

In iOS Safari, the first `click` event may not work

when using `Defer.all()` with `waitForUserAction` set to `true`

and one of the deferred scripts makes a DOM change.

View the discussion [#122](https://code.shin.company/defer.js/discussions/122) for more details.  

**Since**: 2.0  

| Param | Type | Default | Description |

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

| [selector] | <code>string</code> | <code>&quot;[type&#x3D;deferjs]&quot;</code> | A CSS selector that selects target script tags that will be lazy loaded. |

| [delay] | <code>number</code> | <code>0</code> | A timespan, in milliseconds, that the page should wait before executing a script tag. |

| [waitForUserAction] | <code>boolean</code> \| <code>number</code> | <code>false</code> | This argument tells the `Defer.all()` method to delay executing scripts until there is a user interaction. |

**Example**  

Using the magic `type="deferjs"` attribute:

Before:

```html

<script type="text/javascript">

  // your JavaScript is here

  console.log('This script is a normal script tag.');

```

After:

```html

  // your JavaScript will still be here,

  // but it will not run unless the user starts interacting with your page.

  console.info('This script is lazy loaded with type="deferjs" attribute.');

```

**Example**  

Using your value for the type attribute, such as `type="my-magic"`:

If you don't like using the `type="deferjs"` attribute,

you can choose your own by using the `Defer.all()` method.

Notice: To avoid unexpected behavior when using

the `Defer.all()` method to delay executing script tags,

you should call the `Defer.all()` method with a regular script tag.

```html

  // your JavaScript will still be here,

  // but it will not run unless the user starts interacting with your page.

  console.log(

    'This script is lazy loaded with type="my-magic" attribute ' +

    '5 seconds after the user started interacting with your page.'

  );

  Defer.all('script[type="my-magic"]', 5000);

```

**Example**  

Using the `Defer.all()` method for script tags with the `src` attribute:

Your scripts will work perfectly when you mix inline scripts

and script tags with a `src` attribute, like the example below.

The `waitForUserAction` argument (the fifth argument) is set to `true`,

the library will defer loading the tippy.js library until the user starts

interacting. When the user moves their mouse over the button, a tooltip will show.

Notice: To avoid unexpected behavior when using

the `Defer.all()` method to delay executing script tags,

you should call the `Defer.all()` method with a regular script tag.

```html

My button

  tippy('#tooltip-button', { content: 'Hello from Defer.js!' });

  Defer.all('script[type="myscript"]', 500, true);

```

* * *



### Defer.dom([selector], [delay], [unveiledClass], [resolver], [observeOptions]) ⇒ void

The `Defer.dom()` method is useful in the following use cases:

- Lazy loading images, media, iframe tags, etc. on your website.

- Preventing the download of third-party libraries or add-ons unless they are needed.

- Scroll-reveal features, such as handling AJAX updates when a block enters the viewport.

- An element deferred by `Defer.dom()` will be unveiled as soon as the page finishes loading.

An element deferred by the `Defer.dom()` method will be unveiled

when it is about to enter the browser viewport.

The `Defer.dom()` method also converts `data-*` attributes of the elements

into non-data attributes (e.g., from `data-src` to `src`).

Please check out the examples below for more details.

**Kind**: static method of [Defer](#Defer)  

**Since**: 2.0  

| Param | Type | Default | Description |

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

| [selector] | string | "[data-src]" | A CSS selector that selects target HTML elements that will be unveiled later. |

| [delay] | number | 0 | A timespan, in milliseconds, that the page should wait before applying lazy loading to target elements. |

| [unveiledClass] | string |  | Class names that will be added to target elements when they are unveiled. |

| [resolver] | [NodeHandler](#NodeHandler) |  | A [NodeHandler](#NodeHandler) that will check a [Node](#Node) to determine if it will be unveiled or not. If the `resolver()` callback returns `false`, the node will not be unveiled. |

| [observeOptions] | object |  | [Intersection observer options](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API#Intersection_observer_options) |

**Example**  

Using the `data-src` attribute to lazy load image tags.

The browser uses the `src` attribute of

[`` tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img)

to trigger the image load.

It doesn't matter if it is the first or the 1,000th image in your HTML.

If the browser gets the `src` attribute,

it will trigger the image to be downloaded,

regardless of whether it is in or out of the current view.

To defer the load, put the image URL in an attribute other than `src`.

We specify the image URL in the `data-src` attribute of the image tag.

Sometimes, the `src` attribute could be used to download

a very small placeholder image before the real image gets downloaded.

```html



  

  



  Defer.dom('#demo-basic img');

```

**Example**  

Lazy loading a responsive image with `data-srcset` and `data-sizes` attributes.

Using the `srcset` attribute has made

[responsive image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)

sizing much simpler.

It allows you to define a list of differently-sized versions of the same image,

and provide information about the size of each one.

Then, the client (browser) gets to make the decision.

We can also use the same trick as the above example.

We specify an image URL set in `data-srcset` and `data-sizes` attributes of the image tag.

```html



  



  Defer.dom('#demo-srcset img');

```

**Example**  

Lazy loading a responsive image with flexible format selection.

Different browsers support different image formats.

We might want to send a fancy new image format such as

[WebP](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#webp_image)

to browsers that can render it, and fall back to trusty old JPEGs in browsers that can't.

```html



  

    

    

  



  Defer.dom('#demo-picture picture');

```

**Example**  

Basic usage with adding CSS classes.

The `Defer.dom()` method also allows you to add CSS class names when an element is unveiled.

In this example, we will add some CSS classes from Animate.css to make an `` tag animate.

```html



  



  // this example is using animate.css library

  // see: https://animate.style

  Defer.dom('#demo-basic2 img', 0, 'animate__animated animate__backInLeft');

```

**Example**  

Lazy loading inline CSS background images.

We can also defer background images for any HTML tag other than `` or ``.

```html

  #demo-inline .image {

    display: inline-block;

    height: 300px;

    width: 200px;

    background: transparent 0 0 / cover no-repeat;

    border-radius: 150px;

  }



  

  

  



  Defer.dom('#demo-inline .image');

```

**Example**  

Lazy loading CSS background images.

Just another example of lazy loading background images for HTML tags,

but we can also use CSS class names instead of inline `style` attributes.

```html

  #demo-css .image {

    display: inline-block;

    height: 300px;

    width: 200px;

    background: transparent 0 0 / cover no-repeat;

    border-radius: 150px;

  }

  #pic1.shown {

    background-image: url(https://picsum.photos/id/106/400/600);

  }

  #pic2.shown {

    background-image: url(https://picsum.photos/id/206/400/600);

  }

  #pic3.shown {

    background-image: url(https://picsum.photos/id/306/400/600);

  }



  

  

  



  Defer.dom('#demo-css .image', 0, 'shown');

```

**Example**  

Lazy loading a video.

With the `Defer.dom()` method, we can easily defer loading various media tags, such as a `` tag.

```html



  

    

    

    

  



  Defer.dom('#demo-video video', 0, 'shown');

```

**Example**  

Lazy loading an iframe.

With the `Defer.dom()` method, we can effortlessly defer loading iframe tags.

```html



  

  



  Defer.dom('#demo-iframe iframe', 0, 'iframe-loaded');

```

**Example**  

Lazy loading a YouTube video.

This example uses the `Defer.dom()` method to defer loading a YouTube iframe.

```html



  

  



  Defer.dom('#demo-youtube iframe', 0, 'youtube-loaded');

```

**Example**  

Lazy loading a Facebook post.

This example uses the `Defer.dom()` method to defer loading a [Facebook post](https://developers.facebook.com/docs/plugins/embedded-posts/).

```html



  

  



  Defer.dom('#demo-facebook iframe', 0, 'facebook-loaded');

```

**Example**  

Lazy loading a Discord chat box.

This example uses the `Defer.dom()` method to defer loading a Discord chat box.

```html

  Defer.dom('#discord-widget', 0, 'discord-loaded');

```

**Example**  

Scroll and reveal.

The `Defer.dom()` method also helps you perform an action when an element is unveiled.

In this example, when the user scrolls to the bottom of the page,

they will see a message as soon as an element with `id="surprise-me"` appears.

```html

  Defer.dom('#surprise-me', 1000, 'seen', function(node) {

    alert('Yay!\nYou have seen all examples. Have fun with Defer.js!');

  });

```

* * *



### Defer.css(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction]) ⇒ void

We use the `Defer.css()` method to defer loading

external CSS files without blocking the page rendering.

**Kind**: static method of [Defer](#Defer)  

**Note**: (1) Lazy loading behavior changed since v3.0

when you set `Defer.lazy=true` or `waitForUserAction=true`.

The `fileUrl` will not be fetched unless the user starts interacting with your page.  

**Note**: (2) Since v3.8.0, you can set a timeout period in milliseconds for the `waitForUserAction` argument.

If no user interaction occurs within this timeout period, the scripts will still execute.  

**Since**: 2.0  

| Param | Type | Default | Description |

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

| fileUrl | string |  | The URL of the CSS file that should be lazy loaded. |

| [id_or_attributes] | string \| object |  | An ID string or an attribute object for the link tag that should be added to the page. |

| [delay] | number | 0 | A timespan, in milliseconds, that the page should wait before fetching the CSS file. |

| [onload] | function |  | A callback function that will be executed if the CSS file is successfully loaded. |

| [waitForUserAction] | boolean \| number | false | This argument tells the `Defer.css()` method to delay downloading the CSS file until there is a user interaction. |

**Example**  

Using the `Defer.css()` method to lazy load

[FontAwesome](https://fontawesome.com/docs/web/setup/get-started) (CSS and some font files).

```html

  #demo-fontawesome .far {

    font-size: 3em;

    color: green;

  }



  

  @shinsenter/defer.js



  var fileUrl = 'https://pro.fontawesome.com/releases/v5.14.0/css/all.css';

  Defer.css(fileUrl, {crossorigin: 'anonymous'}, 0, function() {

    console.info('FontAwesome is loaded.'); // debug

  });

```

**Example**  

Lazy loading the Animate.css library.

In this example,

we set `waitForUserAction=5000` (the 5th parameter of the `Defer.css` function).

This means the website will wait until there is user interaction

before starting to load the [Animate.css library](https://animate.style/#documentation).

If more than 5 seconds pass without any user interaction,

the library will still be loaded and the scripts will execute.

When the Animate.css library is downloaded,

we will add CSS classes from Animate.css to every tag with `class=".demo"` on the page.

No tag will be animated unless the user scrolls to its position.

```html

  var origin = 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1';

  // This script will lazy load animate.css library

  // only when the page is displayed on a screen-based device

  Defer.css(origin + '/animate.min.css', {media: 'screen'}, 0, function () {

    console.info('Animate.css is loaded.'); // debug

    // adds animation classes to demo blocks.

    Defer.dom('.demo', 100, 'animate__animated animate__fadeIn');

  }, 5000);

```

* * *



### Defer.js(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction]) ⇒ void

We use the `Defer.js()` method to defer loading 3rd-party

JavaScript libraries, widgets, add-ons, etc. without blocking the page rendering.

**Kind**: static method of [Defer](#Defer)  

**Note**: (1) Because the download of a file using the `Defer.js()` method is asynchronous,

to avoid dependency errors when lazy loading a third-party library using the `Defer.js()` method,

it is highly recommended that the `onload` callback function be used

to ensure that the required library is completely defined.  

**Note**: (2) Lazy loading behavior changed since v3.0

when you set `Defer.lazy=true` or `waitForUserAction=true`.

The `fileUrl` will not be fetched unless the user starts interacting with your page.  

**Note**: (3) Since v3.8.0, you can set a timeout period in milliseconds for the `waitForUserAction` argument.

If no user interaction occurs within this timeout period, the scripts will still execute.  

**Since**: 2.0  

| Param | Type | Default | Description |

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

| fileUrl | string |  | The URL of the JavaScript file that should be lazy loaded. |

| [id_or_attributes] | string \| object |  | An ID string or an attribute object for the script tag that should be added to the page. |

| [delay] | number | 0 | A timespan, in milliseconds, that the page should wait before fetching the JavaScript file. |

| [onload] | function |  | A callback function that will be executed if the JavaScript file is successfully loaded. |

| [waitForUserAction] | boolean \| number | false | This argument tells the `Defer.js()` method to delay downloading the JavaScript file until there is a user interaction. |

**Example**  

An alternative way to lazy load the Google Tag Manager script.

Using the `Defer.js()` method to lazy load the Google Tag Manager library and its external scripts.

In this example, we want the GTM to execute as soon as the page is loaded,

so the `waitForUserAction` argument (the fifth argument) is set to `false`.

```html

  var GTM_ID = 'UA-XXXXXXX-Y';

  window.dataLayer = window.dataLayer || [];

  dataLayer.push(['js', new Date()]);

  dataLayer.push(['config', GTM_ID]);

  Defer.js('https://www.googletagmanager.com/gtag/js?id=' + GTM_ID, {'data-id': GTM_ID}, 0, function() {

    console.info('Google Tag Manager is loaded.'); // debug

  }, false);

```

**Example**  

Lazy loading the Prism.js library.

Using Defer.js to lazy load the Prism.js library and its assets.

The `` blocks on the page will be rendered

only when the user scrolls to any `code` block position.


```html

  pre {

    background-color: honeydew;

  }

  // turns on manual mode

  window.Prism = window.Prism || {};

  Prism.manual = true;

  // this script will lazy load Prism.js library and its dark theme.

  // when loading is done, it will apply code formatting to every <code> tag.

  var origin = 'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0';

  Defer.css(origin + '/themes/prism-tomorrow.min.css', 'prism-css');

  Defer.js(origin + '/prism.min.js', 'prism-js', 0, function () {

    // enables code highlighting for code tags using Defer.dom()

    Defer.dom('pre code', 100, 'ide-loaded', Prism.highlightElement, {rootMargin: "120%"});

    console.info('Prism.js is loaded.'); // debug

  });

```

**Example**  

Lazy loading a Twitter post or timeline.

This example uses the `Defer.js()` and the `Defer.dom()` methods to defer loading a [Twitter post or timeline](https://publish.twitter.com).

The `.lazy-timeline` or `.lazy-tweet` blocks on the page will be rendered

only when the user scrolls to the target position.

```html



  

    href="https://twitter.com/xai"

    data-chrome="nofooter noborders"

    data-width="480" data-height="600" data-dnt="true" data-theme="dark">

    Tweets by @xAI

  

  
>

    

  



Defer.js('https://platform.twitter.com/widgets.js', 'twitter-sdk', 0, function() {

  Defer.dom('.lazy-timeline', 0, 'twitter-loaded', function(node) {

    // adds the correct class name for tweet element

    node.className = 'twitter-timeline';

    // For better performance,

    // we only search within the parent DOM tree for uninitialized widgets

    twttr.widgets.load(node.parentNode);

    console.info('Twitter timeline is loaded.'); // debug

  }, {rootMargin: "200%"});

  Defer.dom('.lazy-tweet', 0, 'twitter-loaded', function(node) {

    // adds the correct class name for timeline element

    node.className = 'twitter-tweet';

    // For better performance,

    // we only search within the parent DOM tree for uninitialized widgets

    twttr.widgets.load(node.parentNode);

    console.info('Twitter post is loaded.'); // debug

  }, {rootMargin: "200%"});

});

```

**Example**  

Lazy loading an Instagram post.

This example uses the `Defer.js()` and the `Defer.dom()` methods to defer loading an [Instagram post](https://help.instagram.com/620154495870484).

The `.lazy-instagram` block on the page will be rendered

only when the user scrolls to the target position.

```html



  

    data-instgrm-captioned=""

    data-instgrm-permalink="">

    

  



Defer.js('https://www.instagram.com/embed.js', 'instagram-sdk', 0, function() {

  Defer.dom('.lazy-instagram', 0, 'instagram-loaded', function(node) {

    // adds the correct class name for instagram post

    node.className = 'instagram-media';

    // For better performance,

    // we only search within the parent DOM tree for uninitialized widgets

    instgrm.Embeds.process(node.parentNode);

    console.info('Instagram post is loaded.'); // debug

  }, {rootMargin: "200%"});

});

```

* * *



### Defer.reveal(node, [unveiledClass]) ⇒ void

Programmatically reveal a [Node](#Node) that was lazy loaded by the library.

**Kind**: static method of [Defer](#Defer)  

**Since**: 2.1  

| Param | Type | Description |

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

| node | [Node](#Node) | An HTML node that will be unveiled. |

| [unveiledClass] | string | Class names that will be added to the node when it is unveiled. |

**Example**  

```js

// reveals a single element

var node = document.getElementById('my-video');

Defer.reveal(node);

// reveals multiple elements

document.querySelectorAll('.multi-lazy')

  .forEach(function(node) {

    Defer.reveal(node);

  });

// a shorthand for the above code

document.querySelectorAll('.multi-lazy').forEach(Defer.reveal);

// adds the 'unveiled' classname when an element is unveiled

document.querySelectorAll('.multi-lazy')

  .forEach(function(node) {

    Defer.reveal(node, 'unveiled');

  });

```

* * *



## ~~defer(func, [delay])~~

***Deprecated***

Deprecated from version 2.0

**Kind**: global function  

**See**: [Defer](#Defer)  

**Since**: 1.0  

| Param | Type | Default |

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

| func | function |  | 

| [delay] | number | 0 | 

* * *



## ~~deferimg([selector], [delay], [unveiledClass], [resolver], [observeOptions])~~

***Deprecated***

Deprecated from version 2.0

**Kind**: global function  

**See**: [dom](#Defer.dom)  

**Since**: 1.0  

| Param | Type | Default |

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

| [selector] | string | "[data-src]" | 

| [delay] | number | 0 | 

| [unveiledClass] | string |  | 

| [resolver] | [NodeHandler](#NodeHandler) |  | 

| [observeOptions] | object |  | 

* * *



## ~~deferiframe([selector], [delay], [unveiledClass], [resolver], [observeOptions])~~

***Deprecated***

Deprecated from version 2.0

**Kind**: global function  

**See**: [dom](#Defer.dom)  

**Since**: 1.0  

| Param | Type | Default |

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

| [selector] | string | "[data-src]" | 

| [delay] | number | 0 | 

| [unveiledClass] | string |  | 

| [resolver] | [NodeHandler](#NodeHandler) |  | 

| [observeOptions] | object |  | 

* * *



## ~~deferstyle(src, [id], [delay], [onload])~~

***Deprecated***

Deprecated from version 2.0

**Kind**: global function  

**See**: [css](#Defer.css)  

**Since**: 1.0  

| Param | Type | Default |

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

| src | string |  | 

| [id] | string |  | 

| [delay] | number | 0 | 

| [onload] | function |  | 

* * *



## ~~deferscript(src, [id], [delay], [onload])~~

***Deprecated***

Deprecated from version 2.0

**Kind**: global function  

**See**: [js](#Defer.js)  

**Since**: 1.0  

| Param | Type | Default |

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

| src | string |  | 

| [id] | string |  | 

| [delay] | number | 0 | 

| [onload] | function |  | 

* * *



## Node

An abstract base class upon which many other DOM API objects are based.

**Kind**: global typedef  

**See**: [https://developer.mozilla.org/docs/Web/API/Node](https://developer.mozilla.org/docs/Web/API/Node)  

* * *



## Function

A piece of code that can be executed, or a variable that refers to a function.

**Kind**: global typedef  

**See**: [https://developer.mozilla.org/docs/Glossary/Function](https://developer.mozilla.org/docs/Glossary/Function)  

* * *



## NodeHandler ⇐ [Function](#Function)

A [Function](#Function) that receives a DOM [Node](#Node) object as its argument.

**Kind**: global typedef  

**Extends**: [Function](#Function)  

| Param | Type | Description |

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

| node | [Node](#Node) | A [Node](#Node) object |

* * *

## Documentation in Other Languages

> [NEED HELP] Let's collaborate to make the documentation and examples even better!

### 日本語 (Japanese)

For our Japanese readers, please refer to these helpful articles:

- [Defer.js Documentation (Japanese Translation) by Ataruchi](https://blog.gadgets-geek.net/2023/02/deferjs-doc-japanese.html)

> I would like to express warm gratitude to [@Ataruchi](https://twitter.com/Ataruchi), [@HeavyPeat](https://twitter.com/HeavyPeat), and [Limosuki](https://www.limosuki.com/) for their helpful articles in Japanese.

## Browser Support

Defer.js is compatible with all modern browsers, including:

- 🖥 IE9+ / Edge ^(*)

- 🖥 Firefox 4+

- 🖥 Safari 3+

- 🖥 Chrome

- 🖥 Opera

- 📱 Android 4+

- 📱 iOS 3.2+

^{(*) Legacy browsers like Internet Explorer 9 require the `IntersectionObserver` polyfill.}

## Known Issues

- [Discussion #122](https://code.shin.company/defer.js/discussions/122):

In iOS Safari, the first `click` event may not work as expected when using `Defer.all()` with the `waitForUserAction` argument set to `true` and one of the deferred scripts makes a DOM change.

---

From Vietnam 🇻🇳 with love.