yall.js (Yet Another Lazy Loader)

<p align="center"> <img src="https://img.badgesize.io/malchata/yall.js/main/dist/yall.js?label=Uncompressed" alt="Uncompressed size.">&nbsp;<img src="https://img.badgesize.io/malchata/yall.js/main/dist/yall.js?compression=gzip&label=gzip" alt="gzip size.">&nbsp;<img src="https://img.badgesize.io/malchata/yall.js/main/dist/yall.js?compression=brotli&label=brotli" alt="Brotli size."> </p>

yall.js is a SEO-friendly lazy loader for <video> elements as well as CSS background images. It works in all modern browsers. It uses Intersection Observer where available. yall.js can also monitor the DOM for changes using Mutation Observer 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 <img>, <picture>, and <iframe> elements, as native lazy loading covers these use cases. However, yall.js 4 retains the ability to lazy load autoplaying <video> (ala animated GIFs), lazy loading <video> 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:

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:

// 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, you'll need to use a slightly more verbose syntax:

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

<video>

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

Lazy-loading videos intended as replacements for animated GIFs

yall.js can lazy load <video> elements intended to replace animated GIFs with autoplaying videos:

<video class="lazy" autoplay loop muted playsinline>
  <source data-src="video.webm" type="video/webm">
  <source data-src="video.mp4" type="video/mp4">
</video>

The pattern is largely the same as it is with <picture>, only the lazy class is applied to the <video> 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 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 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:

<video class="lazy" data-poster="placeholder.jpg" controls preload="none">
  <source src="video.webm" type="video/webm">
  <source src="video.mp4" type="video/mp4">
</video>

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 <video> 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 <div> that loads a very large masthead background-image:

<!-- I bet this loads a giant stock photo! -->
<div class="masthead lazy-bg"></div>

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:

/* 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 <noscript>:

<!-- A `<video>` example: -->
<video class="lazy" preload="none" autoplay loop muted playsinline>
  <source data-src="video.webm" type="video/webm">
  <source data-src="video.mp4" type="video/mp4">
</video>
<noscript>
  <video preload="none" autoplay loop muted playsinline>
    <source src="video.webm" type="video/webm">
    <source src="video.mp4" type="video/mp4">
  </video>
</noscript>

<!-- A `<video>` example: -->
<video class="lazy" preload="none" autoplay loop muted playsinline data-poster="img/video-poster.jpg">
  <source src="video.webm" type="video/webm">
  <source src="video.mp4" type="video/mp4">
</video>
<noscript>
  <video preload="none" autoplay loop muted playsinline poster="img/video-poster.jpg">
    <source src="video.webm" type="video/webm">
    <source src="video.mp4" type="video/mp4">
  </video>
</noscript>

Then place a no-js class on the <html> element:

<html class="no-js">

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

<!-- Remove the no-js class on the <html> element if JavaScript is on -->
<script>document.documentElement.classList.remove("no-js")</script>

Normally, this script will remove the no-js class from the <html> 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 <html> element:

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

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"<br> 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"<br> 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"<br> 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<br> The threshold (in pixels) for how far elements need to be within the viewport to begin lazy loading.

events

default: {}<br> An object of events that get sent directly to addEventListener for each element to be lazy loaded. Rather than building an opinionated, bespoke event management system, this sy