🥇 A super small, super efficient library that helps you lazy load almost everything like images, video, audio, iframes as well as stylesheets, and JavaScript.
Filed under dom › utilities

@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.

💡 View document 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 ^(*)

Contributing

Package: @shinsenter/defer.js
Version: 3.8.0
Author: Mai Nhut Tan shin@shin.company
Copyright: 2019-2024 SHIN Company https://code.shin.company/
License: MIT

If you find the project useful, please give it a star or consider donating via PayPal. You can also open a discussion on Github if you have any idea to improve the library.

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 <script> tag just below the opening <head> tag.

<head>
  <meta charset="UTF-8" />
  <title>My Awesome Page</title>

  <!-- Add Defer.js here -->
  <script src="https://cdn.jsdelivr.net/npm/@shinsenter/defer.js@3.8.0/dist/defer.min.js"></script>

  <!-- ... -->
</head>

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 and replacing the comments in the script tag with its content.

<head>
  <meta charset="UTF-8" />
  <title>My Awesome Page</title>

  <!-- Add the Inlined Defer.js here -->
  <script>/* Defer.js content goes here */</script>

  <!-- ... -->
</head>

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.

<head>
  <meta charset="UTF-8" />
  <title>My Awesome Page</title>

  <!-- Put defer_plus.min.js here -->
  <script src="https://cdn.jsdelivr.net/npm/@shinsenter/defer.js@3.8.0/dist/defer_plus.min.js"></script>

  <!-- ... -->
</head>

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.

<script>/* Defer.js content */</script>

<!-- Add the IntersectionObserver Polyfill for legacy browsers -->
<script>'IntersectionObserver'in window||document.write('<script src="https://cdn.jsdelivr.net/npm/@shinsenter/defer.js@3.8.0/dist/polyfill.min.js"><\/script>');</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]) ⇒ void
- .lazy : boolean | number
- .all([selector], [delay], [waitForUserAction]) ⇒ void
- .dom([selector], [delay], [unveiledClass], [resolver], [observeOptions]) ⇒ void
- .css(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction]) ⇒ void
- .js(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction]) ⇒ void
- .reveal(node, [unveiledClass]) ⇒ void
~~defer(func, [delay])~~
~~deferimg([selector], [delay], [unveiledClass], [resolver], [observeOptions])~~
~~deferiframe([selector], [delay], [unveiledClass], [resolver], [observeOptions])~~
~~deferstyle(src, [id], [delay], [onload])~~
~~deferscript(src, [id], [delay], [onload])~~

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 <pre><code></code></pre> blocks to the document as soon as the page finishes loading.

<script>
  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);
</script>

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.

<style>
  body.moving {
    background: linear-gradient(270deg, #c2fff5, #eec3f0, #a1c1ff);
    background-size: 600% 600%;
    animation: moving_bg 30s ease infinite;
  }
</style>

<script>
  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);
</script>

Defer(func, [delay], [waitForUserAction]) ⇒ void
- .lazy : boolean | number
- .all([selector], [delay], [waitForUserAction]) ⇒ void
- .dom([selector], [delay], [unveiledClass], [resolver], [observeOptions]) ⇒ void
- .css(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction]) ⇒ void
- .js(fileUrl, [id_or_attributes], [delay], [onload], [waitForUserAction]) ⇒ void
- .reveal(node, [unveiledClass]) ⇒ 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.all()
Defer.css()
Defer.js()

Kind: static property of Defer
Default: (not set)
Access: public
Since: 3.0
Example
To override the default behavior of the Defer() method:

<!-- You can put this right below the script tag containing defer.min.js -->
<script>Defer.lazy = true;</script>

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.

<!-- You can set a timeout period in milliseconds -->
<script>Defer.lazy = 10000; // 10 seconds</script>

This feature was added since v3.8.0. View some use cases in this discussion.

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

Slow scripts (third-party libraries, add-ons, widgets, etc.) may cause Web Vitals issues in real-world scenarios.

Fully deferring <script> 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 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.
Note: (4) The Resource hints feature was added since v3.2, as it is recommended to prevent issues called "Taming the Waterfall". This feature is discussed in #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 for more details.
Since: 2.0

Param	Type	Default	Description
[selector]	`string`	`"[type=deferjs]"`	A CSS selector that selects target script tags that will be lazy loaded.
[delay]	`number`	`0`	A timespan, in milliseconds, that the page should wait before executing a script tag.
[waitForUserAction]	`boolean` \	`number`	`false`	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:

<script type="text/javascript">
  // your JavaScript is here
  console.log('This script is a normal script tag.');
</script>

After:

<script type="deferjs">
  // 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.');
</script>

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.

<script type="my-magic">
  // 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.'
  );
</script>

<!-- Place the below line after all other script tags -->
<!-- The 2nd argument means those script tags will be delayed 5000ms -->
<script>
  Defer.all('script[type="my-magic"]', 5000);
</script>

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.

<button id="tooltip-button">My button</button>

<script type="myscript" src="https://unpkg.com/@popperjs/core@2"></script>
<script type="myscript" src="https://unpkg.com/tippy.js@6"></script>

<script type="myscript">
  tippy('#tooltip-button', { content: 'Hello from Defer.js!' });
</script>

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

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
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`		A NodeHandler that will check a 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

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

The browser uses the src attribute of <img> tags 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.

<div id="demo-basic">
  <img alt="A lazy image" width="200" height="300" loading="lazy"
       data-src="https://picsum.photos/id/1003/200/300">

  <img alt="A lazy image with a low-resolution placeholder"
       width="200" height="300" loading="lazy"
       src="https://picsum.photos/id/1002/20/30?blur"
       data-src="https://picsum.photos/id/1002/200/300">
</div>

<script>
  Defer.dom('#demo-basic img');
</script>

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

Using the srcset attribute has made responsive image 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.

<div id="demo-srcset">
  <img alt="A lazy image with srcset attribute"
       width="200" height="300" loading="lazy"
       data-sizes="200w"
       src="https://picsum.photos/id/204/20/30?blur"
       data-src="https://picsum.photos/id/204/200/300"
       data-srcset="https://picsum.photos/id/204/400/600 2x, https://picsum.photos/id/204/600/900 3x">
</div>

<script>
  Defer.dom('#demo-srcset img');
</script>

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 to browsers that can render it, and fall back to trusty old JPEGs in browsers that can't.

<div id="demo-picture">
  <picture>
    <source type="image/webp"
         data-sizes="200w"
         data-src="https://picsum.photos/id/1054/200/300.webp"
         data-srcset="https://picsum.photos/id/1054/400/600.webp 2x, https://picsum.photos/id/1054/600/900.webp 3x">

    <img alt="A lazy image with srcset attribute"
         width="200" height="300" loading="lazy"
         data-sizes="200w"
         src="https://picsum.photos/id/1054/20/30?blur"
         data-src="https://picsum.photos/id/1054/200/300"
         data-srcset="https://picsum.photos/id/1054/400/600 2x, https://picsum.photos/id/1054/600/900 3x">
  </picture>
</div>

<script>
  Defer.dom('#demo-picture picture');
</script>

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 <img> tag animate.

<div id="demo-basic2">
  <img alt="A lazy image with animation when loaded"
       width="200" height="300" loading="lazy"
       src="https://picsum.photos/id/1024/20/30?blur"
       data-src="https://picsum.photos/id/1024/200/300">
</div>

<script>
  // this example is using animate.css library
  // see: https://animate.style
  Defer.dom('#demo-basic2 img', 0, 'animate__animated animate__backInLeft');
</script>

Example
Lazy loading inline CSS background images.

We can also defer background images for any HTML tag other than <img> or <picture>.

<style>
  #demo-inline .image {
    display: inline-block;
    height: 300px;
    width: 200px;
    background: transparent 0 0 / cover no-repeat;
    border-radius: 150px;
  }
</style>

<div id="demo-inline">
  <div class="image" data-style="background-image:url(https://picsum.photos/id/1068/400/600)"></div>
  <div class="image" data-style="background-image:url(https://picsum.photos/id/1069/400/600)"></div>
  <div class="image" data-style="background-image:url(https://picsum.photos/id/1070/400/600)"></div>
</div>

<script>
  Defer.dom('#demo-inline .image');
</script>

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.

<style>
  #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);
  }
</style>

<div id="demo-css">
  <div id="pic1" class="image"></div>
  <div id="pic2" class="image"></div>
  <div id="pic3" class="image"></div>
</div>

<script>
  Defer.dom('#demo-css .image', 0, 'shown');
</script>

Example
Lazy loading a video.

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

<div id="demo-video">
  <video autoplay="true" controls="true" muted="true"
         width="480" height="270"
         data-poster="https://storage.googleapis.com/gtv-videos-bucket/sample/images/ForBiggerFun.jpg">
    <source type="video/mp4" data-src="https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4">
    <!-- <source type="video/ogg" data-src="https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.ogg"> -->
    <!-- <source type="video/avi" data-src="https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.avi"> -->
  </video>
</div>

<script>
  Defer.dom('#demo-video video', 0, 'shown');
</script>

Example
Lazy loading an iframe.

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

<div id="demo-iframe">
  <iframe title="An iframe example"
          width="480" height="270" frameborder="0"
          src="about:blank"
          data-src="https://shinsenter.github.io/defer.js/">
  </iframe>
</div>

<script>
  Defer.dom('#demo-iframe iframe', 0, 'iframe-loaded');
</script>

Example
Lazy loading a YouTube video.

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

<div id="demo-youtube">
  <iframe title="Understanding performance with Core Web Vitals"
          width="480" height="270" frameborder="0" allowfullscreen=""
          allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
          src="about:blank"
          data-src="https://www.youtube.com/embed/F0NYT7DIlDQ"
          data-style="background: transparent url(https://img.youtube.com/vi/F0NYT7DIlDQ/hqdefault.jpg) 50% 50% / cover no-repeat;">
  </iframe>
</div>

<script>
  Defer.dom('#demo-youtube iframe', 0, 'youtube-loaded');
</script>

Example
Lazy loading a Facebook post.

This example uses the Defer.dom() method to defer loading a Facebook post.

<div id="demo-facebook">
  <iframe title="An example of Facebook post"
          width="480" height="270" frameborder="0"
          scrolling="no" allowtransparency="true" allow="encrypted-media"
          src="about:blank"
          data-src="https://www.facebook.com/plugins/post.php?href=https%3A%2F%2Fwww.facebook.com%2Fappseeds%2Fposts%2F1502937099839267&amp;width=480&amp;show_text=true&amp;height=200">
  </iframe>
</div>

<script>
  Defer.dom('#demo-facebook iframe', 0, 'facebook-loaded');
</script>

Example
Lazy loading a Discord chat box.

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

<iframe id="discord-widget" title="Discord"
        width="480" height="270" frameborder="0"
        allowtransparency="true" sandbox="allow-popups allow-popups-to-escape-sandbox allow-same-origin allow-scripts"
        src="about:blank"
        data-src="https://discord.com/widget?id=962919929307357234&amp;theme=dark">
</iframe>

<script>
  Defer.dom('#discord-widget', 0, 'discord-loaded');
</script>

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.

<script>
  Defer.dom('#surprise-me', 1000, 'seen', function(node) {
    alert('Yay!\nYou have seen all examples. Have fun with Defer.js!');
  });
</script>

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
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 (CSS and some font files).

<style>
  #demo-fontawesome .far {
    font-size: 3em;
    color: green;
  }
</style>

<div id="demo-fontawesome">
  <i class="far fa-thumbs-up"></i>
  <code>@shinsenter/defer.js</code>
</div>

<script>
  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
  });
</script>

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. 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.

<script>
  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);
</script>

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
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.

<script>
  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);
</script>

Example
Lazy loading the Prism.js library.

Using Defer.js to lazy load the Prism.js library and its assets. The <code> blocks on the page will be rendered only when the user scrolls to any code block position.

<style>
  pre {
    background-color: honeydew;
  }
</style>

<script>
  // 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
  });
</script>

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. The .lazy-timeline or .lazy-tweet blocks on the page will be rendered only when the user scrolls to the target position.

<div id="demo-twitter">
  <a class="lazy-timeline" <!-- the original is class="twitter-timeline" -->
    href="https://twitter.com/xai"
    data-chrome="nofooter noborders"
    data-width="480" data-height="600" data-dnt="true" data-theme="dark">
    Tweets by @xAI
  </a>

  <blockquote class="lazy-tweet" data-width="480" <!-- the original is class="twitter-tweet" -->>
    <!-- content is truncated -->
  </blockquote>
</div>
<script>
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%"});
});
</script>

Example
Lazy loading an Instagram post.

This example uses the Defer.js() and the Defer.dom() methods to defer loading an Instagram post. The .lazy-instagram block on the page will be rendered only when the user scrolls to the target position.

<div id="demo-instagram">
  <blockquote class="lazy-instagram" <!-- the original is class="instagram-media" -->
    data-instgrm-captioned=""
    data-instgrm-permalink="<!-- the URL is omitted -->">
    <!-- content is truncated -->
  </blockquote>
</div>
<script>
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%"});
});
</script>

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

Programmatically reveal a Node that was lazy loaded by the library.

Kind: static method of Defer
Since: 2.1

Param	Type	Description
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

// 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
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
Since: 1.0

Param	Type	Default
[selector]	`string`	`"[data-src]"`
[delay]	`number`	`0`
[unveiledClass]	`string`
[resolver]	`NodeHandler`
[observeOptions]	`object`

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

Deprecated

Deprecated from version 2.0

Kind: global function
See: dom
Since: 1.0

Param	Type	Default
[selector]	`string`	`"[data-src]"`
[delay]	`number`	`0`
[unveiledClass]	`string`
[resolver]	`NodeHandler`
[observeOptions]	`object`

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

Deprecated

Deprecated from version 2.0

Kind: global function
See: 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
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

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

NodeHandler ⇐ `Function`

A Function that receives a DOM Node object as its argument.

Kind: global typedef
Extends: Function

Param	Type	Description
node	`Node`	A 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 <!-- 20240318: I am temporarily hiding the following URLs because their websites have advertisements that could potentially deceive users.
Article by HeavyPeat
Article by Limosuki -->

I would like to express warm gratitude to @Ataruchi, @HeavyPeat, and Limosuki 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: 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.

Show All

JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.

Defer.js

@shinsenter/defer.js

Introduction

Why Choose Defer.js

Contributing

Getting Started

Basic

Inlining the Library

Compatibility with Older Versions

For OLD Browsers (such as IE9)

Functions

Typedefs

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

Defer.lazy : `boolean` | `number`

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

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

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

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

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

defer(func, [delay])

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

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

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

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

Node

Function

NodeHandler ⇐ `Function`

Documentation in Other Languages

日本語 (Japanese)

Browser Support

Known Issues

Defer.js

@shinsenter/defer.js

Introduction

Why Choose Defer.js

Contributing

Getting Started

Basic

Inlining the Library

Compatibility with Older Versions

For OLD Browsers (such as IE9)

Functions

Typedefs

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

Defer.lazy : boolean | number

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

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

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

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

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

defer(func, [delay])

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

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

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

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

Node

Function

NodeHandler ⇐ Function

Documentation in Other Languages

日本語 (Japanese)

Browser Support

Known Issues

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

Defer.lazy : `boolean` | `number`

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

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

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

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

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

NodeHandler ⇐ `Function`