Introduction

I first started using custom elements in 2013, working at ArenaNet in Bellevue, WA. A member of the team was working on the in-game commerce UI for Guild Wars 2, and he took advantage of a Chromium upgrade to create new tags that integrated into the hooks our engine programmers had added. For example, an inventory icon was automatically registered for native UI popups from the game engine, without needing to initialize the view or track its location.

This was pretty basic stuff, but I had always thought about creating new tags as something that only browser developers could do. The new elements in HTML5, like <article> or <nav>, were still fresh in my memory. The idea that we could just make our own tags, with complex behavior and complete control, felt like magic.

A year or two later, at The Seattle Times, I needed a way to insert responsive iframes into a WordPress page for my team's interactive graphics. This is a common problem, but I didn't like the solutions other newsrooms had developed: they felt clunky, requiring a loader script or a few lines of code to initialize each frame. The custom element I built didn't have these issues — it registered itself automatically, and could clean up after itself if it was removed dynamically. I was hooked.

After joining NPR in 2018, I kept finding places where this technology was a natural fit for the problems I was solving. Our 2020 primary coverage not only used them for rich content in our liveblogs, but they were the fundamental architecture for our election results. Although we didn't eliminate the legacy Pym.js embeds that the team had created years prior, a backwards-compatible Sidechain element became a replacement in special projects. Even within our dailygraphics, custom elements became a quick and easy way to offer some standard UI widgets without having to load a new library beyond the D3 we were already using.

Being able to create these tags still feels like magic. They provide an easy and quick way to organize code, true, but they also provide a natural hook for incorporating other web APIs. In explaining how the browser's existing tags work, they give us a window into deeper insight of the platform itself. By giving us a way to hook behavior and styles directly into markup, they reaffirm the three, balanced languages that underly the web. But most importantly, it makes writing HTML feel personal again, like it did when I first learned it to make novelty sites in high school.

You shouldn't need five years of experimentation to see these benefits. This book is an attempt to distill my experience and lessons learned along the way, so that you too can see how expressive, elegant, and fun web components can be. I hope you'll enjoy them as much as I do.

How to read this book

If you've never worked with web components before, you can start at the beginning and work your way through — each chapter is written to lead into the next. I've assumed some fluency with modern JavaScript: you should be comfortable with classes and class inheritance, function binding, and standard DOM methods like querySelectorAll().

I've tried to make sure that even chapters covering basic material still have value for more advanced readers, but feel free to skip ahead if you have prior experience. The chapters are grouped into sections, each of which covers a basic theme or technique.