π₯ A lightweight JavaScript library that helps you lazy load (almost) anything. Defer.js is dependency-free, highly efficient, and optimized for Web Vitals.
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.
- 𧩠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 (*)
- 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.
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:
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>
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>
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>
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.
-
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
-
.lazy :
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])
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
-
.lazy :
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:
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.
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>
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&width=480&show_text=true&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&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>
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>
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>
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');
});
Deprecated
Deprecated from version 2.0
Kind: global function
See: Defer
Since: 1.0
Param | Type | Default |
---|---|---|
func | function |
|
[delay] | number |
0 |
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 |
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 |
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 |
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 |
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
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 |
[NEED HELP] Let's collaborate to make the documentation and examples even better!
For our Japanese readers, please refer to these helpful articles:
I would like to express warm gratitude to @Ataruchi, @HeavyPeat, and Limosuki for their helpful articles in Japanese.
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.
-
Discussion #122:
In iOS Safari, the first
click
event may not work as expected when usingDefer.all()
with thewaitForUserAction
argument set totrue
and one of the deferred scripts makes a DOM change.
From Vietnam π»π³ with love.