The Notsolazyloader

The Notsolazyloader is primarily a tool that allows you to defer the loading of image assets on a webpage if the user is not yet in a position to see them. This greatly improves page load speed and minimizes wasted bandwidth. This tool can lazyload img tags, source tags and also background images which have been added via the stylesheet. However the Notsolazyloader is capable of much more in that you can pass it javascript functions which can be triggered by the proximity of element with a specific ID. Lastly, the Notsolazyloader can be used to improve the appearance of the site loading (reduce image load jank) by applying animations (through the addition of particular classnames). Once the lazyloader knows that the relevant image has fully downloaded in the background, it can then add the relevant classes to the element that will reveal the image, typically with a fade, but any other animation could be used instead.

How to get started

Install notsolazyloader with NPM.

npm i notsolazyloader

Import the module in your js file. The module uses a default export so you can reference with whatever name you like in your file.

import lazyloader from 'notsolazyloader';

Then summon an instance of the module in your js with the lazyloaderInit() method.

lazyloader.lazyloaderInit();

The lazyloader should now be up and running and looking for things to lazyload! For some helpful messages and some indication that the module is working, try changing the debugLogMessages option to true in your js file. Just make sure to set the option before invoking the lazyloaderInit() method.

lazyloader.options.debugLogMessages = true;

lazyloading simple images

In order to lazy load an 'img' tag all you need to do is add the "lazy" class to the img element OR to the parent of the image element (but not both!). Then move the value of the src attribute in the image to a new data attribute on the element called

data-src

Here is an example of an appropriately configured img tag.

<img data-src="http://...the url of the image" class="lazy" src="">

lazyloading background images set in css

css background images can also be lazyloaded. The key is to be able to store the url in the css in such a way that they do not get automatically downloaded when the stylesheet is parsed by the browser. An effective way to do this is to save the url of the image resource in a css custom property which is applied to the element. Then if we also add the 'lazy-bg-image' class to that same html element, the lazyloader will check to see if that element has the '--bgimage' custom property. If it does it will then read the value of that property and apply it as the value of the background image property on the target element.

Here is an example of an appropriately configured element with a lazyloaded background image.

The css:

.my-element {
    --bgimage: url(https://...address of resource)
}

The html:

<div class="my-element lazy-bg-image">...some content...</div>

lazyloading responsive image source tags

Source elements contained within a picture element are excellent for making images responsive, both saving bandwidth and allowing designs to change with the screen size. However, they will still load the asset they deem most appropriate even if that image is far away from the viewport. As a result, lazyloading source elements can still help save more bandwidth and improve page load times.

Lazyloading source elements is essentially like lazyloading image elements in that we place the source url in a data attribute of the source element, but it gets a little more complicated by the possibility of using entry animations. In order for entry animations to work correctly the lazyloader needs to pick the correct image from the source tag and download it in the background. Once the download has finished it will then know to apply the reveal animations (css classes). In order for everything to be in sync and to reveal the image at the right time the lazyloader has to check the screen size and pick the appropriate source element to take the image from. The upshot of this is that we need to be a little more specific with our classnames and rather than just use 'lazy' like we did for 'img' elements, we need to add an extra class to the source element itself to tell the lazy loader which one it is.

The classes include the pixel size that is given to the media attribute of the source element. So for example if the source element is to be used for ipad portrait and up (min-width: 768px) the class name we add to the element would be '768-source'.

Here is an example of an appropriately configured picture element with child source elements. The 'lazy' class needs to be assigned to the picture (or higher parent) element not the source element itself.

<picture class="lazy">
    <source class="768-source" data-srcset="...asset location..." media="(min-width: 768px)" srcset="">

    <source class="0-source" data-srcset="..asset location..." srcset="">
    //this second source tag has no media attribute as it is the default, and/or mobile image
</picture>

The default breakpoints for the sources are 0 and 768. If you have other breakpoints in the media attributes of the the source elements in your project then you can override the default settings and specify your own in the options object.

Options, overrides and defaults

The current default settings for the lazyloader are as follows. Each and any of them can be overridden in the project js file that calls the lazyloader.

const options = {
    rootMargin: "50% 0% 50%",
    threshold: 0,
    extraFunctions: {},
    lazyClass: ".lazy",
    lazyBgClass: ".lazy-bg-image",
    lazySourceElements: [],
    lazyImageElements: [],
    lazyBgImageElements: [],
    extraElements: [],
    legacyElements: [],
    legacySelectors: ['[data-srclegacy]', '[data-bgstylelegacy]'],
    breakpoints: [0, 768],
    mutationElements: [],
    entryAnimationsEnabled: false,
    entryAnimationClasses: ["fadeIn", "animated"],
    debugLogMessages: false
};