auto-lazyload

v1.1.1

Published

17 days ago

A lazy loading library for images, background, videos, Didn't require to change the HTML markup, just works and the performance is amazing!

Downloads

486

0High
0Medium
0Low

erikyo

lazyload image background-image video LCP performance pagespeed animations

Auto Lazy Load

Why?

While lazy loading is hailed as a game-changer in optimizing web performance, not all implementations are created equal. Traditional lazy loaders may inadvertently delay crucial content, leading to detrimental effects on your site's Largest Contentful Paint (LCP). Read more about this and about the Largest Contentful Paint (LCP).

How?

This library allows you to lazyload images, videos, and background images using the Intersection Observer API and the MutationObserver API in order to check when an element is in view. What differs with the common lazy loading implementation is that it doesn't require markup, it's very lightweight and fast to load, remaining full-featured and easy to use.

Usage

Add the script just after the body tag.

Using the iife version

<body>
<script src="https://unpkg.com/auto-lazyload"></script>
...

Using the esm version

install the library with npm install auto-lazyload or yarn add auto-lazyload.

Then import the library with:

<body>
<script type="module">
    import AutoLazyLoad from 'auto-lazyload';
    AutoLazyLoad({
        loading: 'lazy-loading',
        failed: 'lazy-failed',
        on: 'lazy',
        loaded: 'lazy-loaded',
        attribute: 'lazy',
        nativeSupport: false
    });
</script>
...

User Configurable Options

If needed, you have the flexibility to customize the lazy loading behavior by setting the lazyloadOptions object in the window object before the document is loaded. This allows you to override the default options to tailor lazy loading according to your specific requirements.

Example:

window.autolazy = {
    on: 'my-lazy', // the class name for the active lazy loaded image
    loading: 'my-lazy-loading', // the class name for the lazy loading image
    failed: 'my-lazy-failed', // the class name for the failed image
    loaded: 'my-lazy-loaded', // the class name for the lazy loaded image
    attribute: 'data-lazy', // the dataset name for the lazy loaded image (used internally but configurable)
    nativeSupport: false // whether to use the native lazyload (e.g. loading="lazy") or not
    // The intersectionObserverOptions can also be set here
    // https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver#instance_properties
    selector: {
        root: null,
        rootMargin: "0px 0px 0px 0px",
        threshold: 0
    },
};

Api

Observer The intersection observer instance.

const observer = autolazy.observer;

// Example:
observer.rootMargin = "0px 0px 0px 0px";
observer.threshold = 0;

observer.observe(document.querySelector(".target"));
observer.unobserve(document.querySelector(".target"));
observer.disconnect();

Unmount Destroy the library and remove the event listeners.

autolazy.unmount()

Update a target Element Update the options for the specified target.

autolazy.update(".target")

Update Update the options for all targets.

autolazy.update()

Watch Add the specified target to the watch list.

autolazy.watch(document.querySelector(".target"))

Unveil Show the specified target.

autolazy.unveil(document.querySelector(".target"))

window.lazyloadOptions = {
    on: 'my-lazy', // the class name for the active lazy loaded image
    loading: 'my-lazy-loading', // the class name for the lazy loading image
    failed: 'my-lazy-failed', // the class name for the failed image
    loaded: 'my-lazy-loaded', // the class name for the lazy loaded image
    attribute: 'data-lazy', // the dataset name for the lazy loaded image (used internally but configurable)
    nativeSupport: false, // whether to use the native lazyload (e.g. loading="lazy") or not
    fakeImage: 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7', // the fake image url
    // The intersectionObserverOptions can also be set here
    // https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver#instance_properties
    selector: {
        root: null,
        rootMargin: "0px 0px 0px 0px",
        threshold: 0
    },
};

Compatibility

The script is designed to work in modern browsers that support both Intersection Observer and Mutation Observer APIs.
If the IntersectionObserver API is not supported, the page will be loaded without lazy loading images but nothing else.

Contributing

See CONTRIBUTING.md

License

MIT