Imagine we have some JavaScript on a page that updates an element's contents and immediately logs those contents out:
<pre class="language-html"><code class="language-html">&lt;span id="element">
 original text
&lt;/span>

&lt;script>
 document.getElementById('element').innerHTML = "updated text";
 console.log(element.innerHTML);
&lt;/script>
</code></pre>
After loading the page, you'd correctly expect that &quot;updated text&quot; will be displayed on the screen. And when it's exposed via that <code>console.log()</code>, you'll see the same value there too.
The fact that <code>console.log()</code> yields this result isn't surprising because a DOM update is a synchronous event. When the properties of the DOM object are modified, that change is thrown onto the call stack, and no proceeding event can execute until the stack is empty again. This is how JavaScript's event loop does it's thing — first in, first out — even though many of those events simply kick off asynchronous work handled by browser APIs (like <code>setTimeout()</code>, for example).
<h2><a href="#same-thread%3B-different-pace">Same Thread; Different Pace</a></h2>Despite it being synchronous, before a DOM change can be made visible on the screen, <a href="https://developers.google.com/web/fundamentals/performance/critical-rendering-path/render-tree-construction#tldr" target="_blank">several processes</a> occur: the render tree is updated, the layout of the page is reflowed, and the result is finally painted. These processes all operate on the same thread as JavaScript's event loop, but at a different pace. Consider this shoddy illustration I put together:
<img
 data-lazy-src="/post-images/when-dom-updates-appear-to-be-asynchronous/thread.svg"
 width="732"
 height="61"
 alt="the event loop vs. the repaint cycle"
 class="transition-all mx-auto block opacity-0" />
the event loop vs. the repaint cycle
The horizontal bar represents the browser's main thread — everything operates here, unless you're doing something like leveraging Web Workers (and <a href="https://macarthur.me/posts/use-web-workers-for-your-event-listeners" target="_blank">you probably should be</a>).
The smaller vertical bars represent the execution of JavaScript's event loop. It's fast, firing as quickly as it can execute items on the call stack, often communicating with browser APIs along the way.
The thicker vertical bars represent how frequently the browser repaints the screen. That rate usually <a href="https://developers.google.com/web/fundamentals/performance/rendering" target="_blank">sits at around 60 frames/second</a>, or about once every ~16. 66ms. Every time it occurs, it'll take all the DOM changes made between the current paint and the previous paint and make them visible to the user.
Most of the time, the relationship between the event loop and the repaint cycle is inconsequential to our work and virtually irrelevant to the user's experience. But sometimes, circumstances arise when this whole DOM-to-screen process can make us wonder if modifying the DOM really is a synchronous job at all.
<h2><a href="#make-a-dom-update-look-asynchronous-w%2F-alert()">Make a DOM Update Look Asynchronous w/ <code>alert()</code></a></h2>Let's explore one of these circumstances. To do so, I'm using a simple local Node server with a bit of HTML. You're welcome to follow along with the changes we'll be making by <a href="https://github.com/alexmacarthur/dom-updates-and-browser-repaints" target="_blank">cloning the repo for yourself</a> and uncommenting each example as needed. (I considered using something like <a href="https://codesandbox.io/" target="_blank">CodeSandbox</a> for these examples, but I needed an environment as pure &amp; predictable as possible. Platforms that serve a site through an embedded iframe couldn't quite provide that.)
This time around, instead of logging out the modified DOM value, let's expose it with an <code>alert()</code>. When that action is thrown onto the call stack, it'll freeze the main thread, including any outstanding repaints.
<pre class="language-js"><code class="language-js">const element = document.getElementById('element');
element.innerHTML = "updated text";
alert(element.innerHTML);
</code></pre>
After refreshing the page this time, you'll see the &quot;updated text&quot; correctly revealed in the alert box, indicating that the DOM update itself really was synchronous. But if you look at what's actually rendered to the screen, it's probably not what you'd expect:
<img
 data-lazy-src="/post-images/when-dom-updates-appear-to-be-asynchronous/out-of-sync.png"
 width="1800"
 height="902"
 alt="DOM and browser out of sync"
 class="transition-all mx-auto block opacity-0" />
The modification to the DOM object is complete, but the respective repaint has not yet been able to occur (remember — the event loop is turning over much faster than the browser's refresh rate). The instant that the <code>alert()</code> is dismissed, repaints are allowed to proceed, and our text is updated.
<h2><a href="#making-things-unfold-more-predictably">Making Things Unfold More Predictably</a></h2>Again, this quirk is unlikely to trip-up any real-world work, but since we're here anyway, let's toy with making things behave a little more predictably. Say we wanted the <code>alert()</code> to fire only after the DOM change has been rendered to the screen. To do so, we have a couple of options, one of which is hackier than the other.
<h3><a href="#option-%231%3A-delay-the-alert().">Option #1: Delay the <code>alert()</code>.</a></h3>By wrapping our <code>alert()</code> in a <code>setTimeout()</code>, we can wait long enough for any outstanding repaints to occur, and successfully fire it after the updated text has been rendered.
<pre class="language-jsx"><code class="language-jsx">const element = document.getElementById('element');
element.innerHTML = "updated text";

setTimeout(() => {
	alert(element.innerHTML);
}, 20); // &lt;-- arbitrary number greater than refresh rate
</code></pre>
This &quot;works,&quot; but it isn't the most elegant solution, mainly because we're making an educated guess as to when the repaint cycle will have turned over. We don't want to wait too long, causing an unnecessary delay for the <code>alert()</code>. But if we cut it close and the timeout fires sooner than that delay, we're not guaranteed to see the correct text on the screen when it's frozen, because the browser didn't have a chance to paint outstanding DOM changes.
We can illustrate this by setting the timeout's delay to something less than the refresh rate and reload the page a few times. Much of the time, the text will still correctly render. But sooner or later, the rendered text will not have updated like we want.
<pre class="language-jsx"><code class="language-jsx">const element = document.getElementById('element');
element.innerHTML = "updated text";

setTimeout(() => {
	alert(element.innerHTML);
}, 5); // &lt;-- risky, since the delay is less than the browser's refresh rate
</code></pre>
Since we can't undoubtedly predict the refresh rate of the browser (especially considering the range of things that could impact the main thread's throughput overall), this option is pretty far under the bar of &quot;ideal.&quot; Thankfully, the browser offers a built-in API for navigating the repaint cycle by design, providing us with a much friendlier option.
<h3><a href="#option-%232%3A-fire-after-next-repaint">Option #2: Fire After Next Repaint</a></h3>The browser's <code>requestAnimationFrame</code> API lets us <a href="https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame" target="_blank">fire a callback before the browser's next repaint</a>, allowing us to avoid any guessing games in our objective. To use it for our purposes, it's tempting to fire our <code>alert()</code> in one of its callbacks and call it good:
<pre class="language-jsx"><code class="language-jsx">const element = document.getElementById("element");
element.innerHTML = "updated text";

requestAnimationFrame(() => {
	alert(element.innerHTML);
});
</code></pre>
But that won't work. Firing before the next repaint is pointless. Instead, we want it to happen after, since this is when the DOM update will have been painted to the screen. To accomplish this, we just need to nest things a bit:
<pre class="language-jsx"><code class="language-jsx">const element = document.getElementById('element');
element.innerHTML = "updated text";

requestAnimationFrame(() => {
	// fires before next repaint

	requestAnimationFrame(() => {
		// fires before the _next_ next repaint
		// ...which is effectively _after_ the next repaint

		alert(element.innerHTML);
	});
});
</code></pre>
With that, we're good to go! The <code>alert()</code> will only after outstanding DOM changes have been painted to the screen. As a result, what we see in the <code>alert()</code> and what's rendered on the page will consistently be the same:
<img
 data-lazy-src="/post-images/when-dom-updates-appear-to-be-asynchronous/in-sync.png"
 width="1800"
 height="902"
 alt="DOM and browser in sync"
 class="transition-all mx-auto block opacity-0" />
<h2><a href="#the-broader-implications">The Broader Implications</a></h2>Experimenting like this is fun in &amp; of itself, but it should also impact the way you think more broadly about the relationship between the DOM and the browser's rendering engine, especially as it all impacts the performance of your code.
There's more going than what you might think when a DOM attribute is modified, and when the black box of a browser starts to become a little more translucent, it can set you up to understand &amp; tackle tangential problems that impact user experience more apparently, like how certain changes to the DOM trigger synchronous style &amp; layout updates (Paul Irish has <a href="https://gist.github.com/paulirish/5d52fb081b3570c81e3a" target="_blank">a good starter resource</a> on this).
But even if you don't go down a road like that, hopefully this gets you thinking about the the inner-workings of the browser more than before, if for no other reason than to appreciate the tool a little more for all that it does.
Shoutout! All of this was inspired by <a href="https://twitter.com/rauschma/status/1288868746682081285?s=19" target="_blank">a tweet</a> from <a href="https://dr-axel.de/" target="_blank">Dr. Axel Rauschmayer</a>, in which he asked for a safe way to fire an <code>alert()</code> only after a DOM change is visible on the screen. That question and the following discussion got my gears turning to fully understand why the best solution works the way it does.

When DOM Updates Appear to Be Asynchronous

I've been tinkering with the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers" target="_blank">Web Worker API</a> lately, and as a result, I'm really feeling the guilt of not looking into this well-supported tool a lot sooner. Modern web applications are seriously upping demands on the browser's main thread, impacting performance and the ability to deliver smooth user experiences. This tool is just one way to address the challenge.
<h2><a href="#where-things-on('click')ed-for-me">Where Things on('click')ed for Me</a></h2>The advantages of Web Workers are many, but things really clicked for me when it came to the several DOM event listeners in any given application (form submissions, window resizes, button clicks, etc.) These all necessarily live on the browser's main thread, and if that thread is congested by a long-running process, the responsiveness of those listeners begins to suffer, stalling the entire application until the event loop is free to continue firing.
Admittedly, the reason listeners stick out to me so much is due to my initial misunderstanding about the problems Workers are meant to solve. At first, I thought it was mainly about the speed of my code execution, start to finish. &quot;If I can do more on separate threads in parallel, my code will execute so much more quickly!&quot; But! It's pretty common to need to wait for one thing to happen before another can start, like when you don't want to update the DOM until some sort of calculation has taken place. &quot;If I'm gonna have to wait anyway, I don't see the point of moving something into a separate thread,&quot; naive me thought.
Here's the type of code that came to mind:
<pre class="language-javascript"><code class="language-javascript">const calculateResultsButton = document.getElementById(
 "calculateResultsButton"
);
const openMenuButton = document.getElementById("#openMenuButton");
const resultBox = document.getElementById("resultBox");

calculateResultsButton.addEventListener("click", (e) => {
 // "Why put this into a Worker when I
 // can't update the DOM until it's done anyway?"
 const result = performLongRunningCalculation();
 resultBox.innerText = result;
});

openMenuButton.addEventListener("click", (e) => {
 // Do stuff to open menu.
});
</code></pre>
Here, I update the text of a box after performing some sort of presumably heavy calculation. Doing these things in parallel would be pointless (the DOM update necessarily depends on the calculation), so of course I want everything to be synchronous. What I didn't initially understand was that none of the other listeners can fire if the thread is blocked. Meaning: things get janky.
<h2><a href="#the-jank%2C-illustrated">The Jank, Illustrated</a></h2>In the example below, clicking &quot;Freeze&quot; will kick off a synchronous pause for three seconds (simulating a long-running calculation) before incrementing the click count, and the &quot;Increment&quot; button will increment that count immediately. During the first button's pause, the whole thread is at a standstill, preventing any other main thread activities from firing until the event loop can turn over again.
To witness this, click the first button and immediately click the second.
<iframe height="500" style="width: 100%;" scrolling="no" title="Event Blocking - No Worker" src="https://codepen.io/alexmacarthur/embed/XWWKyGe?height=265&amp;theme-id=default&amp;default-tab=result" frameborder="no" allowtransparency="true" allowfullscreen="true">
 See the Pen <a href='https://codepen.io/alexmacarthur/pen/XWWKyGe'>Event Blocking - No Worker</a> by Alex MacArthur
 (<a href='https://codepen.io/alexmacarthur'>@alexmacarthur</a>) on <a href='https://codepen.io'>CodePen</a>.
</iframe>
Frozen, because that long, synchronous pause is blocking the thread. And the impact goes beyond that. Do it again, but this time, immediately try to resize the blue-bordered box after clicking &quot;Freeze.&quot; Since the main thread is also where all layout changes and repainting occur, you're yet again stuck until the timer is complete.
<h2><a href="#they're-listening-more-than-you-think">They're Listening More Than You Think</a></h2>Any normal user would be annoyed to have to deal with an experience like this -- and we were only dealing with a couple of event listeners. In the real world, though, there's a lot more going on. Using Chrome's <code>getEventListeners</code> method, I used the following script to take a tally of all event listeners attached to every DOM element on a page. Drop it into the inspector, and it'll spit back a total.
<pre class="language-javascript"><code class="language-javascript">[document, ...document.querySelectorAll("*")].reduce((accumulator, node) => {
 let listeners = getEventListeners(node);
 for (let property in listeners) {
 accumulator = accumulator + listeners[property].length;
 }
 return accumulator;
}, 0);
</code></pre>
I ran it on an arbitrary page within each of the following applications to get a quick count of the active listeners.
<table>
<thead>
<tr>
<th>Application</th>
<th>Number of Listeners</th>
</tr>
</thead>
<tbody>
<tr>
<td>Dropbox</td>
<td>602</td>
</tr>
<tr>
<td>Google Messages</td>
<td>581</td>
</tr>
<tr>
<td>Reddit</td>
<td>692</td>
</tr>
<tr>
<td>YouTube</td>
<td>6,054 (!!!)</td>
</tr>
</tbody>
</table>
Pay little attention to the specific numbers. The point is that the numbers are big, and if even a single long-running process in your application goes awry, all of these listeners will be unresponsive. That's a lot of opportunity to frustrate your users.
<h2><a href="#same-illustration%2C-but-less-jank-(thx%2C-web-workers!)">Same Illustration, but Less Jank (Thx, Web Workers!)</a></h2>With all that in mind, let's upgrade the example from before. Same idea, but this time, that long-running operation has been moved into its own thread. Performing the same clicks again, you'll see that clicking &quot;Freeze&quot; still delays the click count from being updated for 3 seconds, but it doesn't block any other event listeners on the page. Instead, other buttons still click and boxes still resize, which is exactly what we want.
<iframe height="500" style="width: 100%;" scrolling="no" title="Event Blocking - Worker" src="https://codepen.io/alexmacarthur/embed/qBEORdO?height=265&amp;theme-id=default&amp;default-tab=result" frameborder="no" allowtransparency="true" allowfullscreen="true">
 See the Pen <a href='https://codepen.io/alexmacarthur/pen/qBEORdO'>Event Blocking - Worker</a> by Alex MacArthur
 (<a href='https://codepen.io/alexmacarthur'>@alexmacarthur</a>) on <a href='https://codepen.io'>CodePen</a>.
</iframe>
If you dig into that code a bit, you'll notice that while the Web Worker API could be a little more ergonomic, it really isn't as scary as you might expect (a lot of that scariness is due to the way I quickly threw the example together). And to make things even less scary, there are some good tools out there to ease their implementation. Here are a few that caught my eye:
<ul>
<li><a href="https://github.com/developit/workerize" target="_blank">workerize</a> -- run a module inside a Web Worker</li>
<li><a href="https://github.com/developit/greenlet" target="_blank">greenlet</a> -- run an arbitrary piece of async code inside a worker</li>
<li><a href="https://github.com/GoogleChromeLabs/comlink" target="_blank">comlink</a> -- a friendly layer of abstraction over the Web Worker API</li>
</ul>
<h2><a href="#start-threadin'-(where-it-makes-sense)">Start Threadin' (Where It Makes Sense)</a></h2>If your application is typical, it probably has a lot of listenin' going on. And it also probably does a lot of computing that just doesn't need to happen on the main thread. So, do these listeners and your users a favor by considering where it makes sense to employ Web Workers.
To be clear, going all-in and throwing literally all non-UI work into worker threads is probably the wrong approach. You might just be introducing a lot of refactoring &amp; complexity to your app for little gain. Instead, maybe start by identifying notably intense processes and spin up a small Web Worker for them. Over time, it could make sense to stick your feet in a little deeper and rethink your UI/Worker architecture more at a wider scale.
Whatever the case, dig into it. With their solid browser support and the growing performance demands of modern applications, we're running out of reasons to not invest in tools like this.
Happy threadin'!

For the Sake of Your Event Listeners, Use Web Workers

Back when I was working on <a href="https://github.com/alexmacarthur/slide-element" target="_blank">slide-element</a>, I noticed an issue that would occur when I rapidly toggled an element open &amp; closed. If the previous animation wasn't allowed to finish, the new one would eventually get outta whack, clipping the content on subsequent animations.
<img
 data-lazy-src="/post-images/when-a-weakmap-came-in-handy/slide-element-bad.gif"
 width="316"
 height="168"
 alt="slide-element-bad.gif"
 class="transition-all mx-auto block opacity-0" />
<h2><a href="#the-cause-of-the-weirdness">The Cause of the Weirdness</a></h2>This was happening because each time an animation was triggered, I was grabbing the current &quot;raw&quot; height of the opened element, regardless of whether it was in the middle of an active animation. The library uses the Web Animations API, so the frame construction looked like this:
<pre class="language-jsx"><code class="language-jsx">// For each trigger, animate between zero and the `clientHeight` of the element.
let frames = ["0px", `${element.clientHeight}px`].map((height) => {
 return { height, overflow: "hidden" };
});
</code></pre>
To fix it, I needed to calculate and cache the expanded height once when <code>slide-element</code> is first used, and then refer back to that cached value every time an animation is triggered. That way, for each page load, there'd be one, fixed expanded height value to animate to and from, and no more weirdness caused by rapid clicking.
<h2><a href="#weighing-my-options">Weighing My Options</a></h2>A couple of potential solutions quickly came to mind.
First, storing that value in a <code>data</code> attribute on the target element. This would've done the job, but I have this admittedly weird thing with limiting the amount of data I persist this way. When I inspect the page, I don't want to see a cluster of different attributes cluttering up the markup, particularly if other libraries require their own attributes to exist as well. I've worked with various other tools that, when used in parallel, led to some pretty convoluted markup, and I've been scarred a bit by those experiences. That history and the fact that I was curious if there'd be a more &quot;interesting&quot; way to pull this off, I opted out of this option.
Second, I thought of sticking a &quot;cache&quot; on the <code>window</code> object (deal with it). But there could be several sliding elements on a page at once. So, a single <code>window.seCache</code> (or something like it) variable wouldn't cut it. That value would need to be some sort of key:value pair (like a simple object) in which I could store a reference to each element and the respective expanded height value.
I was open to this general idea, but it had a <code>key</code> (lol) limitation: plain old objects don't permit you to use HTML nodes as properties, so I'd need to require that a unique identifier exist on each element in order to store their expanded heights reliably. That's a change I wasn't eager to make.
<h3><a href="#using-dom-nodes-as-keys">Using DOM Nodes As Keys</a></h3>I was momentarily taken aback after first publishing this post, however, when <a href="https://www.quickwinswithcode.com/" target="_blank">a friend</a> reached out about about the fact that using nodes as property names sorta work within ES2015's <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#computed_property_names" target="_blank">&quot;computed property names&quot;</a> specification. He shared the following sort of example, which kinda blew my mind.
<pre class="language-html"><code class="language-html">&lt;span id="el1">first element&lt;/span>
&lt;span id="el2">second element&lt;/span>

&lt;script>
 const someObj = {
 [document.getElementById('el1')]: 'some value'
 };

 console.log(someObj[document.getElementById('el1')]);
 // 'some value'
&lt;/script>
</code></pre>
Yep, accessing that value via a DOM does return the desired value. But, after digging in a little more, I realized that it wasn't performing a lookup based on the reference to that object. Instead, it was transforming it to a string representation of that object, and then using that as the key:
<pre class="language-js"><code class="language-js">console.log(Object.keys(someObj));
// ['object HTMLSpanElement']
</code></pre>
And that means any of the following would access the same value as well:
<pre class="language-js"><code class="language-js">console.log(someObj[document.getElementById('el2')]);
// 'some value'

console.log(someObj[document.createElement('span')]);
// 'some value'
</code></pre>
While that didn't flesh out, there was another option: a set of new-ish native JavaScript objects that allow you to use objects for keys -- including references to DOM nodes themselves. Those are the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map" target="_blank">Map</a> and <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap" target="_blank">WeakMap</a> objects. For example:
<pre class="language-html"><code class="language-html">&lt;span id="thing" class="thing">a thing.&lt;/span>

&lt;script>
const myWeakMap = new WeakMap();

// Set a value to a specific node reference.
myWeakMap.set(document.getElementById('thing'), 'some value');

// Access that value by passing the same reference.
console.log(myWeakMap.get(document.querySelector('.thing')); // 'some value'
&lt;/script>
</code></pre>
My use of a WeakMap is intentional here. A standard Map would do the trick, but a WeakMap as a marginal advantage in my case: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Keyed_collections#weakmap_object" target="_blank">the keys are not protected from the garbage collection process</a> (thanks to <a href="https://www.reddit.com/user/CreativeTechGuyGames/" target="_blank">CreativeTechGuyGames</a> on Reddit for this tip!). As soon as all other references to an object cease to exist, that item in a WeakMap becomes a candiate for garabage collection, preventing a potential (albeit small) memory leak.
With this tool at my disposal, rigging up an expanded height cache for each target element became relatively straightforward:
<ol>
<li>Create a dedicated WeakMap for storing expanded element heights.</li>
<li>When <code>slide-element</code> is called on an element, create a key in that WeakMap and store the full, pre-animated height.</li>
<li>Whenever it's needed, first check that WeakMap for the height for the respective node.</li>
</ol>
In rather contrived &amp; simplified code, the logic came to look something like this:
<pre class="language-javascript"><code class="language-javascript">window.seCache = window.seCache || WeakMap.new();

function getExpandedHeight() {
 // We already have the calculated height.
 if(window.seCache.get(element)) {
 return window.seCache.get(element);
 }

 // This is the first run. Calculate &amp; cache the full height.
 element.style.display = "block";
 window.seCache.set(element, element.clientHeight);
 element.style.display = "none";

 return window.seCache.get(element);
}

// For each trigger, animate between zero and the `clientHeight` of the element.
let frames = ["0px", `${getExpandedHeight()}px`].map((height) => {
 return { height, overflow: "hidden" };
});
</code></pre>
And there we have it. A far more interesting solution than 2010's data attributes. 😜
<h2><a href="#way-more-useful-than-i-thought">Way More Useful Than I Thought</a></h2>For whatever reason, I didn't think there'd be much utility to a brand new JavaScript object that enables you to use objects as keys, as well as anything other feature it offered (why wouldn't a basic object cover my every need?). So, when I finally came across a use case for it, I got pretty pumped. Hopefully, this all nudges your mind to think of the tool when the appropriate need arises.
Apologies to whomever proposed this thing.

When a JavaScript WeakMap() Actually Came in Handy

Preloading JavaScript Assets in WordPress

When you're looking to incorporate any given feature into your WordPress application, there's rarely a shortage of third-party plugins out there to make it happen. But sometimes, whether you're trying to avoid the inevitable complexity an unfamiliar third-party plugin introduces, or for some other reason, you might feel called to take a stab at developing that feature on your own. Lazy loading images could be one of these features, and fortunately, it's fairly simple to set it up yourself and start reaping the performance benefits.
I'm assuming here that you have full development dominion over your WordPress application, and that you're relatively familiar with the <a href="https://codex.wordpress.org/Plugin_API" target="_blank">WordPress Plugin API</a> -- the characteristic hook system that makes WordPress development as flexible as it is. While we could set up lazy loading without a plugin by putting everything inside your theme's <code>functions.php</code> file, we'll be rolling our own extremely basic plugin. This is generally a good idea over just using your theme -- it'll separate concerns a little better, you'll be able to switch themes without losing functionality, and it'll be easy to toggle whenever like, which is particularly helpful when debugging.
Know this: I won't be going in-depth on the philosophy of what makes a well-crafted WordPress plugin. Experiment and argue about all that jazz on your own. I'm just gonna give you the bare bones of what it takes to make a lazy loading plugin with just a few lines of code. Let's get started.
<h2><a href="#set-up-your-plugin">Set Up Your Plugin</a></h2>In your plugins directory, create a <code>simple-lazy-loading</code> directory and a file inside it named <code>simple-lazy-loading.php</code>. Open that file, and place the following at the top:
<pre class="language-php"><code class="language-php">&lt;?php
/*
* Plugin Name: Simple Lazy Loading
*/
</code></pre>
At bare minimum, you now have a plugin that can be activated in the the WordPress admin. Head there and switch it on.
<img
 data-lazy-src="/post-images/build-your-own-simple-lazy-loading-functionality-in-wordpress/simple-lazy-loading.jpg"
 width="1408"
 height="176"
 alt="Activate Simple Lazy Loading Plugin"
 class="transition-all mx-auto block opacity-0" />
After you've done that, open up the file you just created and we're ready to go!
<h2><a href="#let's-get-lazy">Let's Get Lazy</a></h2>You can lazy load a lot of things, but here, we're just focusing on lazy loading images stored in your WordPress database that are spit out as post or page content. Basically, images you upload and use via the WordPress admin.
To do this, let's use <a href="https://github.com/ApoorvSaxena/lozad.js" target="_blank">Lozad</a> for our lazy loading JavaScript library. It has no jQuery dependency, appears to be pretty actively maintained, and it leverages the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API" target="_blank">Intersection Observer API</a>, which will get you better performance, especially as browser support grows in the future. In the meantime, there's a <a href="https://github.com/w3c/IntersectionObserver/tree/master/polyfill" target="_blank">polyfill</a> you can include.
<h3><a href="#getting-lozad-up-on-its-feet">Getting Lozad Up on Its Feet</a></h3>First, enqueue the Lozad library. We'll also want to throw in the official W3C polyfill for the Intersection Observer API. We'll enqueue both of these in the footer because we're responsible web developers and don't want these scripts to block page rendering.
<pre class="language-php"><code class="language-php">add_action('wp_enqueue_scripts', function () {
 wp_enqueue_script( 'intersection-observer-polyfill', 'path-to-intersection-observer.js', [], null, true );
 wp_enqueue_script( 'lozad', 'https://cdn.jsdelivr.net/npm/lozad@1.3.0/dist/lozad.min.js', ['intersection-observer-polyfill'], null, true );
});
</code></pre>
Next, initialize Lozad. Out of the box, a &quot;lozad&quot; class is used to watch for elements to be lazy loaded, but since we're going to modify the configuration a bit anyway, let's change that to a more generic &quot;lazy-load&quot; class. Also, note that I'm just using <code>wp_add_inline_script</code> here, since the amount of JS we're writing is small. You're welcome to put that in a separate JS file -- just make sure it executes after <code>lozad</code> is loaded.
<pre class="language-php"><code class="language-php">add_action('wp_enqueue_scripts', function () {
 wp_enqueue_script( 'intersection-observer-polyfill', 'path-to-intersection-observer.js', [], null, true );
 wp_enqueue_script( 'lozad', 'https://cdn.jsdelivr.net/npm/lozad@1.3.0/dist/lozad.min.js', ['intersection-observer-polyfill'], null, true );
 wp_add_inline_script( 'lozad', '
 lozad(".lazy-load").observe();
 ');
});
</code></pre>
Neat! But what if I don't want to target elements by class? No problem! Instead of defining a class to be watched, you can pass in a <code>NodeList</code>. In that case, our <code>wp_add_inline_script</code> section would look something more like this:
<pre class="language-php"><code class="language-php">wp_add_inline_script( 'lozad', '
	var myElements = document.querySelectorAll("#main img");
	lozad(myElements).observe();
');
</code></pre>
If we set things up this way, Lozad will watch for any images that are children to <code>#main</code>.
Our next step is to add our target class to every image we want to lazy load, as well as change the <code>src</code> attribute to <code>data-src</code>. This will prevent the browser from loading the images by default (which would block the rest of the page from rendering), and only do so when <code>lozad</code> changes <code>data-src</code> back to <code>src</code>, which will happen when users scroll to those images.
For any images on custom pages outside of the WordPress database, it's pretty easy to set up the attributes we need. Just manually do it. Unfortunately, working with the images that are stored in the database will require that we filter everything via <code>the_content</code> hook. I don't love the idea of having to filter post content like this, but if you're properly caching your site like you should be, this is less of an issue, at least in terms of performance.
<pre class="language-php"><code class="language-php">add_filter('the_content', function ($content) {
	//-- Change src to data attributes.
	$content = preg_replace("/&lt;img(.*?)(src=)(.*?)>/i", '&lt;img$1data-$2$3>', $content);

 	//-- Change srcset to data attributes.
 	$content = preg_replace("/&lt;img(.*?)(srcset=)(.*?)>/i", '&lt;img$1data-$2$3>', $content);

	//-- Add .lazy-load class to each image that already has a class.
	$content = preg_replace('/&lt;img(.*?)class=\"(.*?)\"(.*?)>/i', '&lt;img$1class="$2 lazy-load"$3>', $content);

	//-- Add .lazy-load class to each image that doesn't already have a class.
	$content = preg_replace('/&lt;img((.(?!class=))*)\/?>/i', '&lt;img class="lazy-load"$1>', $content);

	return $content;
});
</code></pre>
We're doing three separate things with our filter here.
<ul>
<li>Changing <code>src</code> and <code>srcset</code> attributes to <code>data-src</code> and <code>data-srcset</code> on each image.</li>
<li>Adding a <code>lazy-load</code> class to each image so Lozad can properly target the images we want to lazy load.</li>
<li>Adding a <code>lazy-load</code> class to each image that doesn't already have a class attached to it.</li>
</ul>
Technically, you're done. Now, each page on which you have content populated from the WordPress editor, images should not load by default, and instead load only when they come into view. But that might not be good enough.
<h3><a href="#let's-make-it-all-prettier">Let's Make It All Prettier</a></h3>If images only load when they come into view, you'll see an ugly pop on the page when that happens. To make everything happen in a prettier fashion, we have some options at our disposal.
Let's adjust the <code>rootMargin</code> so images start loading when they're about to come into view. This way, they can be ready to go before the user even gets there, and everything will appear much more seamless. Go back to our <code>wp_add_inline_script</code> call:
<pre class="language-php"><code class="language-php">wp_add_inline_script( 'lozad', '
	lozad(".lazy-load", {
		rootMargin: "300px 0px"
	}).observe();
');
</code></pre>
Now, when images come within 300px of being visible, Lozad will trigger them to start loading. Feel free to adjust that value as you see fit.
We can also add a class after our images load, so they fade in a super pretty, majestic way. Do that by adding a <code>loaded</code> callback:
<pre class="language-php"><code class="language-php">wp_add_inline_script( 'lozad', '
	lozad(".lazy-load", {
		rootMargin: "300px 0px",
		loaded: function (el) {
			el.classList.add("is-loaded");
		}
	}).observe();
');
</code></pre>
And add some CSS that'll hide the images until they're fully loaded, and then allow them to fade in. Note that if you do add the following CSS, you'll need to enqueue it in a stylesheet or by some other means.
<pre class="language-css"><code class="language-css">.lazy-load {
 transition: opacity .15s;
 opacity: 0;
}

.lazy-load.is-loaded {
 opacity: 1;
}
</code></pre>
Neat! Now, every image will now have an <code>opacity</code> of <code>0</code>, until they're loaded in, when <code>is-loaded</code> will fade them in.
<h3><a href="#soon%2C-this-may-all-be-meaningless">Soon, This May All Be Meaningless</a></h3>Lazy loading is a good, responsible thing to implement, but, all of this will likely be possible by default in browsers. In fact, <a href="https://web.dev/native-lazy-loading/" target="_blank">Chromium-based browsers and Firefox already do have a native API for it</a>. So, pay attention. In a short while, all of what I've just showed you might be pointless, and I will need to put a sad disclaimer at the top of this post that you might just be wasting your time by reading this.
Hope this helps!

I'm Alex MacArthur.

Featured Blog Posts

When DOM Updates Appear to Be Asynchronous

For the Sake of Your Event Listeners, Use Web Workers

When a JavaScript WeakMap() Actually Came in Handy