Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/malchata/yall.js

A fast, flexible, and small SEO-friendly lazy loader.
https://github.com/malchata/yall.js

autoplay background image lazy-load lazy-loading lazyload lazyload-script lazyloading performance poster video webperf

Last synced: 4 days ago
JSON representation

A fast, flexible, and small SEO-friendly lazy loader.

Awesome Lists containing this project

README 

        
# yall.js (Yet Another Lazy Loader)





  Uncompressed size. gzip size. Brotli size.




yall.js is a SEO-friendly lazy loader for `` elements as well as CSS background images. It works in all modern browsers. It uses [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) where available. yall.js can also monitor the DOM for changes using [Mutation Observer](https://hacks.mozilla.org/2012/05/dom-mutationobserver-reacting-to-dom-changes-without-killing-browser-performance/) to lazy load elements that have been appended to the DOM after initial load, which may be desirable for single page applications.



yall.js 4 removes lazy loading for ``, ``, and `` elements, as [native lazy loading](https://web.dev/browser-level-image-lazy-loading/) covers these use cases. However, yall.js 4 retains the ability to lazy load autoplaying `` (ala animated GIFs), lazy loading `` element `poster` images, as well as CSS background images.



To use yall, grab `yall.min.js` (or `yall.min.mjs` if you're the modern sort) from the `dist` directory and slap it on your page. You can also install it with npm:



```shell

npm install yall-js

```



## Usage



This is version 4 of yall.js, and introduces a named export named `yall` rather than a single default export:



```javascript

// Import y'all

import { yall } from "yall-js";



// Invoke!

yall();

```



The above syntax is sufficient if you don't want to pass in any options. [If you _do_ want to specify options](#api-options), you'll need to use a slightly more verbose syntax:



```javascript

// Import y'all

import { yall } from "yall-js";



// Invoke!

yall({

  observeChanges: true

});

```



From there, lazy loading elements depends on _what_ you want to lazy load. Let's take a look at what you can do with it.



### ``



yall.js covers two possible lazy loading patterns for video.



#### Lazy-loading videos intended as replacements for animated GIFs



yall.js can lazy load `` elements intended to [replace animated GIFs with autoplaying videos](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/replace-animated-gifs-with-video/):



```html



  

  



```



The pattern is largely the same as it is with ``, only the `lazy` class is applied to the `` element. **Tip:** If you're embedding videos that _don't_ emulate animated GIFs (i.e., non autoplaying video), it's better to _not_ lazy load them. Instead, use the [`preload` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#attr-preload) to defer loading of video content. Please also note that video autoplay policies can change at any time, meaning your video may not autoplay on some platforms! Such behaviors are not bugs, but rather features designed to respect users' bandwidth and preferences. Filing issues related to video autoplay issues will likely be rejected, as yall.js can't (and won't) override browser policies.



#### Lazy-loading `poster` placeholder images for non-autoplaying video



Sometimes you have video you'd rather not autoplay, such as those with an audio track. Or, perhaps you want to be more considerate of your user's bandwidth (how nice of you). In these cases, the [`poster` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#attr-poster) can be used to load a placeholder image. However, these images can also be rather large, especially if you have a number of videos on the page that use this pattern. You can lazy load `poster` images with the following markup pattern:



```html



  

  



```



This pattern is slightly different than the one before it. Because we're not trying to emulate animated GIFs, we've removed a number of attributes from the `` element that aren't necessary in this case:



1. We've done away with the usual `data-src` attribute, and specified `preload="none"` to ensure the browser doesn't preload any portion of the video (which, depending on the browser, can't be guaranteed).

2. To lazy load the `poster` image itself, we specify the image to load in a `data-poster` attribute.

3. The `controls` attribute is added here to allow the user to control video playback.



**Note:** For the sake of your users, don't mix the above markup patterns. If a video is going to use `autoplay` to replace an animated image, lazy loading a placeholder image via `data-poster` isn't necessary. Furthermore, if you're unsure of what to do, _let browsers handle this stuff and don't use yall.js to manage loading of videos at all!_



### CSS images



Last, but not least, you can use yall.js to lazy load images referenced in CSS. This might be useful if you have a very large `background-image` you'd like to defer. Proper use of this feature requires _both_ HTML and CSS. To start, let's say you have a `
` that loads a very large masthead `background-image`:



```html





```



The key here is the `lazy-bg` class, which is a class yall.js looks for (and can be changed in the options). When yall.js sees elements with this class, it will remove that class and replace it with a class of `lazy-bg-loaded` (also changeable in the options). From here, it's up to you to author CSS that makes use of this class to swap the image in. Such CSS might look like this:



```css

/* Pre-lazy loading styles */

.masthead {

  background: #e6e6e6; /* A little placeholder color */

  height: 16.66vw;

  margin: 0 0 1rem;

}



/* BAM! Lazy loaded! */

.masthead.lazy-bg-loaded {

  background: url("masthead.jpg");

}

```



This works because, unlike HTML which loads most resources regardless of their visibility, CSS loads resources only if the current layout builds a CSSOM which includes them. That means if your document's style tree changes later on to request a background image, the browser will fetch it the moment the change is applied. Leaning on this behavior is more sensible than using a mess of `data-` attributes pointing to possible image candidates, which could potentially add a bunch of extra markup and introduce edge cases that are difficult to code for.



## What about users without JavaScript?



Slap on some ``:



```html



  

  



  

    

    

  



  

  



  

    

    

  



```



Then place a `no-js` class on the `` element:



```html



```



Finally, add this one line `` before any `<link>` or `<style>` elements in the document `<head>`:



```html

<!-- Remove the no-js class on the <html> element if JavaScript is on -->

<script>document.documentElement.classList.remove("no-js")

```



Normally, this script will remove the `no-js` class from the `` element as the page loads, but if JavaScript is turned off, this never happens. From there, you can add some CSS that hides elements with a `class` of `lazy` when the `no-js` class is present on the `` element:



```css

/* Hide .lazy elements if JavaScript is off */

.no-js .lazy {

  display: none;

}

```



To see all these examples in action, clone the repo, install packages, run `npm test`, and check out the demos on your local machine at [http://localhost:8080](http://localhost:8080).



## API options



When you call the main `yall` initializing function, you can pass an in an options object. Here are the current options available:



### `lazyClass`



**default:** `"lazy"`


The element class used by yall.js to find elements to lazy load. Change this is if a `class` attribute value of `lazy` conflicts with your application.



### `lazyBackgroundClass`



**default:** `"lazy-bg"`


The element class used by yall.js to find elements to lazy load CSS background images for. Change this if you'd prefer not to use the default.



### `lazyBackgroundLoaded`



**default:** `"lazy-bg-loaded"`


When yall.js finds elements using the class specified by `lazyBackgroundClass`, it will remove that class and put this one in its place. This will be the class you use in your CSS to bring in your background image when the affected element is scrolled into the viewport.



### `threshold`



**default:** `200`


The threshold (in pixels) for how far elements need to be within the viewport to begin lazy loading.



### `events`

**default:** `{}`


An object of events that get sent directly to [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) for each element to be lazy loaded. Rather than building an opinionated, bespoke event management system, this system gets out of your way and lets you to specify whatever events are possible to bind with `addEventListener`. Here's an example below:



```javascript

yall({

  events: {

    // The object key is sent as the first argument to `addEventListener`,

    // which is the event. The corresponding value can be the callback if you

    // don't want to send any options to `addEventListener`.

    load: function (event) {

      if (!event.target.classList.contains("lazy")) {

        event.target.classList.add("yall-loaded");

      }

    },

    // If we want to pass options to the third argument in `addEventListener`,

    // we can use a nested object syntax like so:

    error: {

      // Here, the `listener` member is the callback.

      listener: function (event) {

        if (!event.target.classList.contains("lazy") && event.target.nodeName == "VIDEO") {

          event.target.classList.add("yall-error");

        }

      },

      // The option below is sent as the third argument to `addEventListener`,

      // offering more control over how events are bound. If you want to

      // specify `useCapture` in lieu of options pass a boolean here instead.

      options: {

        once: true

      }

    }

  }

});

```



Events for yall.js are bound at initialization time (often `DOMContentLoaded`). This means that some events _could_ fire multiple times, depending on the event. For instance, in the above `load` event example, you can see that we check for the default class of `lazy` on the element. This is because the `load` event could fire when the initial image placeholder loaded (if one is specified) _and_ when the final image is lazy loaded.



The advantage of this approach is that you can do pretty much anything you want in any of the events on the elements yall.js observes. The disadvantage is that it places the responsibility squarely on you to manage events. If you think yall.js has a bug in this behavior, do your due diligence to research whether your event callback code is buggy before filing issues.



### `observeChanges`



**default:** `false`


Use a `MutationObserver` to monitor the DOM for changes. This is useful if you're using yall.js in a single page application and want to lazy load resources for markup injected into the page after initial page render.



### `observeRootSelector`



**default:** `"body"`


If `observeChanges` is set to `true`, the value of this string is fed into `document.querySelector` to limit the scope in which the Mutation Observer looks for DOM changes. The `` element is monitored by default, but you can confine the observer to any valid CSS selector (e.g., `#main-wrapper`).



### `mutationObserverOptions`



**default:** `{ childList: true, subtree: true }`


Options to pass to the `MutationObserver` instance. Read [this MDN guide](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver#MutationObserverInit) for a list of options. It's very possible that changing this value could result in yall.js failing to lazy load resources that are appended to the DOM later on.



## Words of advice



Unlike previous versions of yall-js, compatibility back to IE 11 is no longer a goal. If you need compatibility with older browsers, install the previous release of yall.js like so:



```shell

npm i [email protected]

```



Also, it is not this script's job to minimize [layout shifts](https://web.dev/cls/) for you. [Use appropriate `width` and `height` attributes](https://www.smashingmagazine.com/2020/03/setting-height-width-images-important-again/), styles, and lightweight placeholders for your images.



For `` elements, avoid lazy loading a placeholder with the `data-poster` attribute for autoplaying videos and just use `poster`. On the other hand, _do_ consider lazy loading a placeholder image with `data-poster` for non-autoplaying videos. Or you can opt _not_ to use a `poster` image. Your website, your call.



Also, do _not_ lazy load resources that are likely to near the top of the page—or "above the fold", as it were. Doing so is an anti-pattern in that those resources will not begin loading until yall.js has been loaded, which may take much longer than if those resources were loaded normally. Such a pattern will negatively affect your page's [LCP](https://web.dev/lcp/).



## Contributing



Please read the [contribution guidelines](https://github.com/malchata/yall.js/blob/master/CONTRIBUTING.md). If you think I'm some kind of grumpy crank after reading that, please remember that this is a hobby project you can use for free.