This book explains Web Components. Additionally, it shows how to create a simple and small layer (a so-called thin library) around the native HTML 5 API to make your life as a developer a lot easier. Such a library is available as an Open Source project called @nyaf – Not Yet Another Framework. It’s not a requirement, but reduces the hurdles to use Web Components significantly and avoids the jump into the full blown frameworks and libraries such as Angular or React.

Who Should Read this Book?

This book is aimed at both, beginners and experienced web developers. The code is mainly TypeScript, few examples are pure ECMAScript.

In any case, I tried not to ask any prerequisites or conditions to the reader. You do not need to be a computer scientist, not in perfect command of language, don’t need to know rocket science. No matter in what context you have encountered on Web Components, you should be able to read this text. However, the most benefit from this book gets everybody already working on frontend stuff. Especially those overwhelmed with frameworks, techniques and monstrous project structures will learn what modern Web development has to offer. Nowadays all modern browsers are able to execute ES2015 and above natively and transpilers such as Babel or TypeScript makes it easy to adapt.

What You Should Know

Readers of my books have hardly any requirements. Some HTML cannot harm and who already have seen a static HTML page (the source code, of course) is certainly well prepared. I assume that you have at least a current operating system, on that you will find an editor with which you can create web pages.

Web Components are not that demanding. But they are made by an API on top of the HTML 5 API. This API is offered through JavaScript. Hence, as an additional requirement, you should be able to read JavaScript and have a basic understanding of TypeScript.

As You Can Read this Text

I will not dictate how you should read this text. In the first draft of the structure, I have tried several variations and found that there exists no ideal form. However, reader tend today to consume smaller chunks, independent chapters, and focused content. This book supports this trend by reducing it to a small issue, focused and with no “blah-blah” for the inflation of the volume.

Beginners should read the text as a narrative from the first to the last page. Those who are already somewhat familiar can safely skip certain sections.

Conventions used in the Book

The theme is not easy to master technically, because scripts are often too wide and it would be nice if one could support the best optical reading form. I have therefore included extra line breaks used to aid readability, but that’s not required in the editor of your development environment.

In general, each program code is set to a non-proportional font. In addition, most scripts have line numbers:

1 customElements.define('show-hello', class extends HTMLElement {
2   connectedCallback() {
3     const shadow = this.attachShadow({mode: 'open'});
4     shadow.innerHTML = `<p>
5       Hello, ${this.getAttribute('name')}
6     </p>`;
7   }
8 });

If you think you need to enter something in the prompt or in a dialog box, this part of the statement is in bold:

$ npm install typescript

The first character is the prompt and is not entered. In the book I use the Linux prompt from the bash shell. The commands will work, without any exception, unchanged even on Windows. The only difference then is the command prompt C:> or something similar at the beginning of the line. Usually the instructions are related to relative paths or no paths at all, so the actual prompt shouldn’t matter despite the fact that you shall be in your working folder.

Expressions and command lines are sometimes peppered with all types of characters, and in almost all cases, it depends on each character. Often, I’ll discuss the use of certain characters in precisely such an expression. Then the “important” characters with line breaks stay alone and in this case, too, line numbers are used to reference the affected symbol in the text exactly (note the : (colon) character in line 2):

1 a.test {
2   :hover {
3     color: red
4   }
5 }

The font is non-proportional, so that the characters are countable and opening and closing parentheses are always in the same column.

Symbols

To facilitate the orientation in the search for a solution, there is a whole range of symbols that are used in the text.

Preparations

To use the code in the book you need this:

• A machine with NodeJs v10+ installed. Any desktop OS will do it, whether as Windows, MacOS, or Linux. Windows users can use any shell, WSL or CMD or Powershell. Of course, any shell on Linux is good enough, too.
• An editor to enter code. I recommend using Visual Studio Code. It runs on all mentioned operating systems. Webstorm is also an amazing powerful editor.
• A folder where the project is being created. Easy enough, but keep your environment clean and organized like a pro.

This book comes with a lot of examples and demo code. It’s available on Github at:

• https://github.com/joergkrause/webcomponent-book.

The folders are structured following the book, chapter by chapter.

If you’re relatively new in the Web development field, test your knowledge by cloning the repo, bring the examples to live and watch the outcome. Read the text and add your own stuff once you know that the environment is up and running.

Using the @nyaf Library

The author of this book has years of experience with Web components. After several projects, smaller and bigger ones, the frustration was growing about the lack of support for simple tasks and the burden of huge frameworks that intentionally solve these burdens, but come with an overwhelming amount of additional features. None of the frameworks felt right. I suspect that most developer support code has a similar trigger, so I decided to start my own library project. It’s called nyaf - Not Yet Another Framework. It’s just a thin library, few Kilobytes only, and it solves just the basic needs:

• A thin wrapper to handle Web components in TypeScript code very well
• A router to have full single page application support
• Support for data binding and form validation
• A Flux based store to get a professional architecture

It’s split into three parts, so you just use what you want and skip the features not (yet) needed.

About the Author

Jörg works as a trainer, consultant and software developer for major companies worldwide. Build up on the experience of 25 years of work with web and many, many large and small projects.

Jörg believes it is especially important to have solid foundations. Instead of always running to create the latest framework, many developers would be better advised to create and provide a robust foundation.

Jörg has written over 60 titles in the renowned and prestigious specialist publishers in German and English, including some bestsellers for Carl Hanser, Apress, and O’Reilly.

Anyone who wants to learn this subject compact and fast, its right here. On his website www.joergkrause.de much more information can be found.

Contact the Author

In addition to the website, you can also direct contact him over at www.IT-Visions.de. If your business needs professional advice about web topics or a continuing education/ training session for software developers, please contact Jörg through his Website or book directly via http://www.IT-Visions.de.

1 Introduction

Web components are a set of standards to make self-contained components: custom HTML-elements with their own properties and methods, encapsulated DOM and styles. The technology is natively supported by all modern browsers and does not require a framework. The API has some quicks and quirks though. I will explain those obstacles it in great detail, but it’s helpful to know that you can make your life easier. A thin wrapper library to handle common tasks is the answer. This is what the @nyaf – Not Yet Another Framework – code is for. A full description can be found in the appendix. However, all examples and explanations within the book chapters are completely independent. Of course you can use any other component library.

1.1 The Global Picture

This section describes a set of modern standards for Web Components.

Components

The whole component idea is nothing new. It’s used in many frameworks and elsewhere. Before we move to implementation details, imagine how the internals of a page in a browser is being described. You have a tree of simple elements, defined by the language HyperText Markup Language (HTML). You also have the ability to describe the appearance of each element using Cascading Style Sheets (CSS). You have the ability to manipulate both parts dynamically at runtime using ECMAScript (also known as JavaScript). The most important point in this description is the word “tree”. Elements form a tree, where one or more elements are the children of another one.

If the basic structure of a page is already a tree of smaller parts (see Figure 1-1), it makes sense and simplifies development, if on a higher level the elements form a tree too. Such a unit, hierarchical collections of functionality that can form a tree, is called a component.

A page hence consists of many components. Each component, in its turn, has many smaller details inside. At the end, it’s still pure HTML.

The components can be very complex, sometimes more complicated than websites itself. How such complex units are created? Which principles we could borrow to make our development same-level reliable and scalable? Or, at least, close to it.

Component Architecture

The well known rule for developing complex software is: don’t make complex software. If something becomes complex – split it into simpler parts and connect them in the most obvious way. A good architect is the one who can make the complex simple to handle for the developer. (That’s not the same as an UX designer, who makes the complex application simple to use for the end user; but that’s an entirely different story.)

You can split user interfaces into visual components: each of them has its own place on the page, can “do” a well-described task, and is separate from the others.

Let’s take a look at a website (see Figure 1-2), for example Twitter. It naturally splits into components:

1. Top navigation
2. Main menu
3. User profile
4. Tweet feed
5. Suggestions
6. Trending subjects

Components may have sub-components, e.g. messages may be part of a higher-level “message list” component. A clickable user picture itself may be a component, and so on. It boils down to HTML eventually. If there is no more simplification a native element forms a leave in the tree. The profile branch may end with an <img> tag, then.

How do we decide, what a component is? That comes from intuition, experience and common sense. Usually it’s a separate visual entity that we can describe in terms of what it does and how it interacts with the page. In the case above, the page has blocks, each of them plays its own role, it’s logical to make these components. If you’re new to this software architecture, it’s a good advise to keep a component smaller than the typical size of your screen. In reality, that means the lines of code that form the component shall fit on your standard monitor using your favorite font size. For me, it’s a maximum of 100 lines of code. If my components grow, I try to split them in smaller chunks. However, always keep the logical structure in mind. If two parts of a component differ significantly and both may use only 25 lines of code, it’s still a good idea to split it up and have clean code instead of clinging to the 100 lines¹ rule.

Parts of a Component

A component has several parts. These can be splittet into several files or appear in just one file. It mainly depends on the environment you use and the strategy to create, compile and deploy the final code. In a logical view these are the parts:

• A JavaScript or TypeScript class.
• A DOM structure, managed solely by its class, so outside code doesn’t access it (the “encapsulation” principle).
• CSS styles, applied to the component. These can be isolated or global.
• An API: events, class methods etc. that interact with other components or application parts.

Once again, the whole “component” thing is nothing special. It’s just a clever approach to handle the complexity of web pages in a way an average human being can understand.

There exists many frameworks and development methodologies to build them, each with its own bells and whistles. Usually, special CSS classes and conventions are used to provide “component feel” – CSS scoping and DOM encapsulation. “Web components” provide built-in browser capabilities for that, so we don’t have to emulate them any more. That’s one of the most powerful developments we saw in the recent years to raise in the realm of web development. Unfortunately, the “component frameworks”, especially Angular, Vue, and React seem to be seen by developers as the final solution, the solely way to create components. We understand that’s because it brings users and makes the framework more useful. But it’s not entirely true. The native stuff is almost as good as these frameworks as you will see soon. However, don’t ask an Angular fellow. What should she say?

Web Components bring some basic features that makes them so extraordinarily useful.

• Custom elements – to define custom HTML elements.
• Shadow DOM – to create an internal DOM for the component, hidden from the other parts of the app.
• CSS Scoping – to declare styles that only apply inside the Shadow DOM of the component.
• Event re-targeting and other minor stuff to make custom components better fit the development requirements.

In the next chapters I’ll go into details of such components – the fundamentals and well-supported features of web components that are really good on its own. Also, some smart stuff written around it will be explained to show how you can work very closely on the comfort level of Angular or React without actually using them.

1.2 The Raise of Thin Libraries

After digging deeper into the Web Component world it seems that there is no need for a full framework like Angular or React anymore. However, some repeating tasks are boring and error prone. Hence a small layer around the basic API would be helpful. That was the beginning of the famous @nyaf thin library. It’s not called a framework because even with two more modules that became part of the package it’s very small, indeed. These additional modules are first @nyaf/forms that is responsible for bi-directional binding and validation. Second, the @nyaf/store module is a simple yet powerful Flux based store. It simplifies the architecture of huge applications dramatically.

One of the clear approaches from the beginning was the avoidance of dependencies. You need this and nothing more. Another approach is the interaction with any existing library. Even pure jQuery code will not harm the usage of @nyaf. And, finally, it’s pure ES2015+ and there are no polyfills or additions for elder browsers. Modern browsers have a market share of 96% and that’s what you target. The full documentation is added as an appendix to this book for your reference.

Single Page Apps

A single-page application (SPA) is a web application or website that interacts with the web browser by dynamically rewriting the current web page with new data from the web server, instead of the default method of the browser loading entire new pages. The goal is faster transitions that make the website feel more like a native app.

In a SPA, all necessary HTML, JavaScript, and CSS code is either retrieved by the browser with a single page load, or the appropriate resources are dynamically loaded and added to the page as necessary, usually in response to user actions. The page does not reload at any point in the process, nor does control transfer to another page. The location hash or the HTML5 History API can still be used to provide the perception and navigability of separate logical pages in the application.

Web Components make it easy to create SPAs. The main part is a feature called “router”. The router routes a call (usually a click on a hyperlink or button) by using an assigned URL to some kind of management code. That code creates a new tree of components and moves it to a particular target element. The browser reacts to this operation by rendering the elements. The developer has to make these decisions to get it working:

1. Define a target – an element where the replaceable tree appears. We call this usually an “outlet”.
2. Create a definition that maps routes to components. This is a “router configuration”.

Again, some convenient stuff can be created to make your daily life easier. See chapter “Single Page Apps” for more details of possible implementations.

The HTML 5 API

The HTML 5 API is amazingly powerful and covers a wide range of features. All existing frameworks and libraries – with no exception – are build on top of this API. The advantage of using a certain framework is primarily that you get a simplified view, a reduced view, a more elegant API style or even more robust code made by additional error handling. These are all good reasons to use a framework or library, ain’t these?

Imagine you know all these APIs. What would happen is that you can avoid few of the libraries and probably a whole framework. The code is finally smaller, faster, and easier to maintain. Learning the HTML 5 APIs is essential for web developers nowadays.

The Template Language

A template language simplifies the creation of forms. It’s not enforced, you can af course use the basic API and pure HTML. In complex applications you’ll see that there is lot of repeating code. There are many template languages available and I’ll present few of them so you can compare and choose freely.

Smart Decorators

Instead of splitting the definition and registration the component itself covers all necessary information as meta-data. Decorators are feature of the TypeScript compiler and eventually they will become part of the ECMAScript standard.

This coding style supports the “separation of concern” principle and is easy to implement. A final solution could look like this:

1 @CustomElement('app-main')
2 export class MainComponent extends BaseComponent<{}> {
3 
4   protected render() {
5     return (<h1>Demo</h1>);
6   }
7 
8 }

The decorator CustomElement is called in the instantiation process of the class. It can access both, the underlying function definition and the instance. Here you can manipulate the code further (at runtime) by adding hidden properties, for example. Other code fragments may access these properties and act according these hidden instructions. In the above example some external code may see this and take ist as an “please register me” instruction. The advantage here is that the component developer doesn’t need to think about such infrastructure stuff and the code is much smaller and easier to read.

TypeScript

TypeScript is not covered in this book. It is, however, the language used to write components and related libraries. It’s not exactly necessary for writing Web components, but it’s a strong tool in the developers toolset. The ability to transform JSX has already been explained and if you don’t use TypeScript you have to replace one tool with another. So avoiding it gains nothing, while embracing it gives a bunch of advantages.

One of the main reasons for its success is, that valid JavaScript is valid TypeScript. Any ES2015 example shown here will be accepted by the TypeScript transpiler. What’s added is the ability to use features from newer JavaScript versions such as ECMAScript 2020 today, even if the browser do not have full support yet. And it adds types that reduce error prone code. In short it is this:

TypeScript = JavaScript + Type System

TypeScript is compatible with ECMAScript² 2018 and provides necessary polyfills.

WebPack

WebPack is an open-source JavaScript module bundler, primarily for JavaScript, but it can transform front-end assets like HTML, CSS, and images if the corresponding loaders are included. Webpack takes modules with dependencies and generates static assets representing those modules. The dependencies and generated dependency graph allows web developers to use a modular approach for their web application development purposes. It can be used from the command line, or can be configured using a configuration file which is named webpack.config.js³. This file is used to define rules, plugins, etc., for a project.

WebPack is highly extensible via rules which allow developers to write custom tasks that they want to perform when bundling files together. NodeJs is required for using webpack, hence it’s a command line tool running at development time.

1.3 Compatibility

For every new technology it takes some time until all browsers and tools have a fully working implementation. The great news about the year 2020 is, that meanwhile all browsers (see Figure 1-3) have full support and you rarely need a polyfill.

1.4 Other Libraries

Apart from the one I feature in this book, @nyaf, there are few others that I found worth mentioning here. They differ in focus and quality. It depends on your project and feature requirements which one suits better. It’s also a good idea to analyse them and learn how things work internally and consider going with some code where you have the ownership. The following list is pulled from webcomponents.org:

• Hybrids is a UI library for creating web components with simple and functional API. The library uses plain objects and pure functions for defining custom elements, which allow very flexible composition. It provides built-in cache mechanism, template engine based on tagged template literals, and integration with developer tools.
• LitElement uses lit-html to render into the element’s Shadow DOM and adds API to help manage element properties and attributes. LitElement reacts to changes in properties and renders declaratively using lit-html.
• Polymer is a web component library built by Google, with a simple element creation API. Polymer offers one- and two-way data binding into element templates, and provides shims for better cross-browser performance.
• Skate.js is a library built on top of the W3C web component specs that enables you to write functional and performant web components with a very small footprint. Skate is inherently cross-framework compatible. For example, it works seamlessly with – and complements – React and other frameworks.
• Slim.js is a lightweight web component library that provides extended capabilities for components, such as data binding, using ES2015 native class inheritance. This library is focused for providing the developer the ability to write robust and native web components without the hassle of dependencies and an overhead of a framework.
• Stencil is an open source compiler that generates standards-compliant web components.

2 Making Components

We can create custom HTML elements, described by a class, with its own methods and properties, events and so on. Once a custom element is defined, we can use it on par with built-in HTML elements. These elements are called Web Components.

2.1 Basics

That’s great, as HTML dictionary is rich, but not infinite. There are no <easy-tabs>, <sliding-carousel>, or <beautiful-upload>. Just think of any other tag we might need.

We can define them with a special class, and then use as if they were always a part of HTML.

There are two kinds of custom elements:

• Autonomous custom elements – custom elements, extending the abstract HTMLElement class.
• Customized built-in elements – extending built-in elements, like a customized button, based on HTMLButtonElement etc.

First I’ll cover autonomous elements, and then move to customized built-in ones.

To create a custom element, we need to tell the browser several details about it: how to show it, what to do when the element is added or removed to page, etc. That’s done by making a class with special methods. That’s easy, as there are only few methods, and all of them are optional.

A sketch with the full list is shown in Listing 2-1:

 1 class MyElement extends HTMLElement {
 2   constructor() {
 3     super();
 4     // element created
 5   }
 6 
 7   connectedCallback() {
 8     this.innerHTML = '<h1>Hello Web Component</h1>';
 9     // called when the element is added to the document
10   }
11 
12   disconnectedCallback() {
13     // called when the element is removed from the document
14   }
15 
16   static get observedAttributes() {
17     return [
18       /* array of attribute names to monitor for changes */
19     ];
20   }
21 
22   attributeChangedCallback(name, oldValue, newValue) {
23     // called when one of attributes listed above is modified
24   }
25 
26   adoptedCallback() {
27     // called when moved to a new document
28   }
29 
30   // there can be other element methods and properties
31 }

All methods shown are optional, implement those you really need only. Be aware that under certain circumstances the methods might be called multiple times.

After defining the component, we need to register it as an element. We need to let the browser know that <my-element> is served by our new class.

customElements.define('my-element', MyElement);

Now for any HTML elements with the tag <my-element> an instance of MyElement is created, and the aforementioned methods are called. We also can use document.createElement('my-element') to create the element through an HTML 5 API call and attach the element later to the DOM.

A custom element name must have a hyphen -, e.g. my-element and super-button are valid names, but myelement is not.

To load and use the component you need an HTML page. This could look as simple as shown in Listing 2.2.

 1 <!DOCTYPE html>
 2 <html lang="en">
 3   <head>
 4     <meta charset="UTF-8" />
 5     <meta name="viewport"
 6           content="width=device-width, initial-scale=1.0" />
 7     <title>Document</title>
 8     <script src="component.js"></script>
 9   </head>
10   <body>
11     <my-element></my-element>
12   </body>
13 </html>

It’s recommended to wait for the document ready state before applying the registration. This might or might not change the behavior – it depends on the inner construction of the component’s content. But waiting for the ready event seems to fix some common issues and has rarely any disadvantages.

A First Example

For example, there already exists a <time> element in HTML, for date and time information. But it doesn’t do any formatting by itself.

Let’s create <time-format> element that displays the time in a nice, language-aware format as shown in Listing 2-3.

 1 class TimeFormat extends HTMLElement {
 2 
 3   connectedCallback() {
 4     let date = new Date(this.getAttribute('datetime')
 5                 || Date.now());
 6 
 7     this.innerHTML = new Intl.DateTimeFormat('default', {
 8       year: this.getAttribute('year') || undefined,
 9       month: this.getAttribute('month') || undefined,
10       day: this.getAttribute('day') || undefined,
11       hour: this.getAttribute('hour') || undefined,
12       minute: this.getAttribute('minute') || undefined,
13       second: this.getAttribute('second') || undefined,
14       timeZoneName: this.getAttribute('time-zone-name')
15                  || undefined,
16     }).format(date);
17   }
18 }
19 
20 customElements.define('time-format', TimeFormat);

To use it, the following piece of HTML is necessary (Listing 2-4).

 1 <time-format
 2   datetime="2020-04-13"
 3   year="numeric"
 4   month="long"
 5   day="numeric"
 6   hour="numeric"
 7   minute="numeric"
 8   second="numeric"
 9   time-zone-name="short"
10 ></time-format>

The class has only one method connectedCallback() – the browser calls it when a <time-format> element is added to the document and it uses the built-in Intl.DateTimeFormat² data formatter, well-supported across the browsers, to show a nicely formatted time. We need to register our new element by customElements.define(tag, class). And then we can use it everywhere. The output is shown in Figure 2-1.

Observe Unset Elements

If the browser encounters any <time-format> elements before customElements.define got called, it will not produce an error. The element is yet unknown, just like any non-standard tag. It will render into nothing. That’s hard to capture. To make it visible we could add an style that’s using the pseudo CSS selector :not(:defined).

When customElement.define is called, the element is “upgraded”. A new instance of the TimeFormat class is created for each element, and the connectedCallback method is called. The element becomes :defined, then.

A very helpful stylesheet to achieve the visibility of not yet upgraded components is shown in Listing 2-5:

 1 <style>
 2   :not(:defined) {
 3     display: block;
 4     width: 150px;
 5     border-bottom: 2px dotted red;
 6     text-align: center;
 7   }
 8   :not(:defined):before {
 9     content: "unknown element !";
10     color: red;
11   }
12 </style>

In the example the JavaScript part is missing (to simulate an error) and hence the style makes the element visible. The result is shown in Figure 2-2:

Custom Elements API

To get information about custom elements, there are two helpful methods:

• customElements.get(name) – returns the class for a custom element with the given name

- customElements.whenDefined(name) – returns a promise that resolves (without value) when a custom element with the given name becomes upgraded.

It’s important to start the rendering in connectedCallback, not in the constructor. In the example above, element content is rendered (created) that way. The constructor is not suitable. When the constructor is called, it’s yet too early. The element is created, but the browser did not yet process and assign attributes at this stage. For instance, calls to getAttribute would return null.

An additional reason is performance. In the further stages of the render process some code might decide not to render the element or replace the render content with some message. Imagine a grid, which might become huge, but due to some attribute setting it’s replaced by a “to many data” message. Processing all attributes first and render then makes sense.

The connectedCallback method triggers when the element is added to the document. Not just appended to another element as a child, but actually becomes a part of the page. So we can build detached DOM, create elements and prepare them for later use. They will only be actually rendered when they make it into the page. In the first examples that’s always the case, because the element is written directly into the page. However, in a more dynamic environment, such as a Single Page App (SPA), this would not be the same.

2.2 Observing Attributes

In the current implementation of <time-format>, after the element is rendered, further attribute changes doesn’t have any effect. That’s strange for an HTML element. Usually, when we change an attribute, like href of an anchor element, we expect the change to be immediately visible. All kind of effects and animations need this behavior.

We can observe attributes by providing their list in the observedAttributes() method. It’s static (not part of the prototype), because it’s global definition once for all instances of the element. For such attributes, the method attributeChangedCallback is called when they are modified. It doesn’t trigger for any other attribute for performance reasons.

Listing 2-6 shows a new <time-format> version that auto-updates when attributes change.

 1 class TimeFormat extends HTMLElement {
 2 
 3   render() {
 4     let date = new Date(this.getAttribute('datetime')
 5                 || Date.now());
 6 
 7     this.innerHTML = new Intl.DateTimeFormat("default", {
 8       year: this.getAttribute('year') || undefined,
 9       month: this.getAttribute('month') || undefined,
10       day: this.getAttribute('day') || undefined,
11       hour: this.getAttribute('hour') || undefined,
12       minute: this.getAttribute('minute') || undefined,
13       second: this.getAttribute('second') || undefined,
14       timeZoneName: this.getAttribute('time-zone-name')
15                  || undefined,
16     }).format(date);
17   }
18 
19   connectedCallback() {
20     if (!this.rendered) {
21       this.render();
22       this.rendered = true;
23     }
24   }
25 
26   static get observedAttributes() {
27     return ['datetime', 'year', 'month', 'day', 'hour',
28             'minute', 'second', 'time-zone-name'];
29   }
30 
31   attributeChangedCallback(name, oldValue, newValue) {
32     this.render();
33   }
34 
35 }
36 
37 customElements.define("time-format", TimeFormat);

The usage doesn’t look much different from the first example.

<time-format id="elem"
             hour="numeric"
             minute="numeric"
             second="numeric">
</time-format>

However, when you change one of the observed attributes in your code, the element re-renders automatically:

const elem = document.querySelector('time-format');
setInterval(
  () => elem.setAttribute('datetime', new Date()),
  1000
);

The rendering logic is moved to render() helper method. We call it once when the element is inserted into the document. After a change of an attribute, listed in observedAttributes(), the method attributeChangedCallback triggers and re-renders the element. The call to the render method must be implemented in the component. On the first look it’s not much magic here and in comparison with frameworks such as Angular or React it might feel primitive. But the ability to control the rendering and have a clear cycle makes the implementation very handy and straight.

Attribute Data

The component itself can handle only scalar values. That means you’re limited to string, boolean, and number. Anything else will run through toString() and may end up as something like [Object object] or, in case of null as a string “null”. That’s a lot weaker than the binding we can see in Angular, for example. Of course, a private implementation can detect such types and use JSON.stringify and JSON.parse. That is, indeed, the slowest but most robust way to serialize complex data.

Another way is to ditch the usage of observed attributes completely and use a programmatic way. This would, however, limit the component to be accessible by code only. That’s a serious limitaton indeed, but let’s explore an example (Listing 2-7) anyway to give you the idea.

 1 class ObjectComponent extends HTMLElement {
 2 
 3   render() {
 4     this.innerHTML = null;
 5     const pre = document.createElement('pre');
 6     pre.innerHTML = JSON.stringify(this.content);
 7     this.insertAdjacentElement('afterbegin', pre);
 8   }
 9 
10   connectedCallback() {
11     this.render();
12   }
13 
14   static get observedAttributes() {
15     return ['content'];
16   }
17 
18   attributeChangedCallback(name, oldValue, newValue) {
19     this.content = newValue;
20     this.render();
21   }
22 
23   set content(value) {
24     this._content = value;
25     this.render();
26   }
27 
28   get content() {
29     return this._content;
30   }
31 
32 }
33 
34 document.addEventListener('readystatechange', (docEvent) => {
35   if (document.readyState === 'complete') {
36     customElements.define("obj-element", ObjectComponent);
37 
38     document.querySelector('button')
39             .addEventListener('click', (e) => {
40       document.querySelector('obj-element').content = {
41         type: 'object'
42       };
43     });
44   }
45 });

The key is line 19 with access to the custom property content. Here we assign an object and call the render method immediately. That bypasses the conversion to string type and keeps the stringifyer working as expected. Figure 2-3 shows the expected result.

The observation is still present to allow a static value for initialization (see Listing 2-8).

1 <obj-element content="Default String Content"></obj-element>
2 <hr>
3 <button type="button" >Click to change content to object</button>

Discussing the Options

To monitor external data without the ability to use the observation you may also consider using a Proxy object and optionally the MutationObserver class. Both ways use ES 2015 classes and are hence native APIs. A Proxy gives you the ability to intercept the access to an object’s properties. Whatever and whenever some code outside accesses a property, a callback is being called. This could be used to trigger the render method.

The MutationObserver Type

A MutationObserver on the other hand monitors the DOM itself and calls a callback if something changes. However, this function runs in a mikrotask and is not entirely synchronous. That means, the new attribute value (if observed) may not have the current value already. To not expose a risk of non-deterministic behavior the MutationRecord instance that the callback returns will not give access to the new value. Of course, there are several ways to patch the prototype or add an interceptor, but it all feels hackish and not very reliable. The biggest risk is that the API changes internally without any notification and the code will fail eventually out of nowhere with a simple browser update. I made some experiments with this and never found a satisfying solution. Just in case you want to dig deeper into this, the following code snippet gives you the general usage of such an observer:

 1 document.addEventListener('readystatechange', (docEvent) => {
 2   if (document.readyState === 'complete') {
 3 
 4     const observer = new MutationObserver(mutations => {
 5       console.log('mutations', mutations);
 6     });
 7 
 8     customElements.define("obj-element", ObjectComponent);
 9 
10     document.querySelector('button')
11             .addEventListener('click', (e) => {
12       // observed by MutationObserver
13       document.querySelector('obj-element').setAttribute('content',
14       { type: 'object' });
15     });
16     // just observe the attributes
17     observer.observe(
18       document.querySelector('obj-element'),
19       { attributes: true }
20     );
21   }
22 });

Proxy

A Proxy class is pure JavaScript and handles just an object. But, a Web component is an object, so this sounds like a feasible solution. However, the amount of boilerplate code is significant. In a real life scenario you would move this to a base class, but the example shows nonetheless the weakness of HTML 5 API (and it’s power, too).

 1 class ObjectComponent extends HTMLElement {
 2 
 3   constructor() {
 4     super();
 5     this.proxy = new Proxy(
 6       this, {
 7       get: () => { return this.content; },
 8       set: (target, prop, value) => {
 9         this._content = value;
10         if (ObjectComponent.observedAttributes.includes(prop)) {
11           this.setAttribute(prop, JSON.stringify(value));
12         }
13         return true;
14       }
15     });
16   }
17 
18   render() {
19     this.innerHTML = null;
20     const pre = document.createElement('pre');
21     pre.innerHTML = JSON.stringify(this.content);
22     this.insertAdjacentElement('afterbegin', pre);
23   }
24 
25   connectedCallback() {
26     this.render();
27   }
28 
29   static get observedAttributes() {
30     return ['content'];
31   }
32 
33   attributeChangedCallback(name, oldValue, newValue) {
34     if (!oldValue) {
35       this.setAttribute('content', JSON.stringify(newValue));
36     }
37     if (oldValue !== newValue) {
38       this.render();
39     }
40   }
41 
42   set content(value) {
43     this.proxy.content = value;
44   }
45 
46   get content() {
47     return JSON.parse(this.getAttribute('content'));
48   }
49 
50 }
51 
52 document.addEventListener('readystatechange', (docEvent) => {
53   if (document.readyState === 'complete') {
54 
55     customElements.define("obj-element", ObjectComponent);
56 
57     document.querySelector('button')
58             .addEventListener('click', (e) => {
59       document.querySelector('obj-element').content = {
60         type: 'object'
61       };
62     });
63 
64   }
65 });

Again, there is no way to use the programmatic access here:

document.querySelector('obj-element').content = ...

Because the attribut observation is still operational the external access from HTML would work too. Insofar it does exactly what’s expected. The external access and the programmatic access both write into the property content. That’s observed by the proxy handler’s setter path. Here we look that’s really an observed attribute (line 10) and trigger the regular attribute observer (line 11). The difference is, that the value received by the proxy is still an object (while the internal API would have called toString first and delivers [Object object]). Now we can transform it into the stringified version and store this in the attribute. The actual render code expects an object (line 21). To make it working and makes use of the JSON.parse method to return an actual object in a transparent way, the getter method at the end (line 47) transforms the string back.

2.3 Rendering Order

When the browser’s HTML parser builds the DOM, elements are processed one after another, parents before children. Imagine we have something like that:

<outer-element><inner-element></inner-element></outer-element>

Then an <outer-element> element is created and connected to DOM first, and then <inner-element>.

That leads to important consequences for custom elements. For example, if a custom element tries to access innerHTML in connectedCallback, it gets nothing:

1 customElements.define(
2   'user-info',
3   class extends HTMLElement {
4     connectedCallback() {
5       alert(this.innerHTML);
6     }
7   }
8 );

<user-info>Joerg</user-info>

If you run it, the alert is empty. That’s exactly because there are no children on that stage, the DOM is unfinished. HTML parser connected the custom element <user-info>, and is going to proceed to its children, but they’re not here yet.

If you like to pass information to custom elements, we can use attributes. They are available immediately.

Delay Access

If we really need the content immediately, we can defer access to them with a zero-delay setTimeout.

 1 <script>
 2 customElements.define('user-info', class extends HTMLElement {
 3 
 4   connectedCallback() {
 5     setTimeout(() => alert(this.innerHTML));
 6   }
 7 
 8 });
 9 </script>
10 
11 <user-info>Joerg</user-info>

Now the alert shows “Joerg”, because we run it asynchronously and the HTML parsing is complete. Of course, this solution is not perfect. If nested custom elements also use setTimeout to initialize themselves, then they queue up: the outer setTimeout triggers first, and then the inner one. And that’s simply the wrong order.

Let’s demonstrate that with an example:

 1 <script>
 2 customElements.define('user-info', class extends HTMLElement {
 3   connectedCallback() {
 4     console.log(`${this.id} connected.`);
 5     setTimeout(() => console.log(`${this.id} initialized.`));
 6   }
 7 });
 8 </script>
 9 
10 <user-info id="outer">
11   <user-info id="inner"></user-info>
12 </user-info>

Output order:

• outer connected
• inner connected
• outer initialized
• inner initialized

We can clearly see that the outer element finishes initialization before the inner one.

There’s no built-in callback that triggers after nested elements are ready. If needed, we can implement such thing on our own. For instance, inner elements can dispatch events like initialized, and outer ones can listen and react on them.

Introducing a Life Cycle

The current implementation of a Web Component is very simple. That makes it easy to get in the first step, but some additional implementation effort is required. One idea to solve the issues with the last example is to introduce a loading callback. Once the render stage has passed the component fires a event or – even better – resolves a Promise. The outer component can wait for this to happen and proceed once the children confirm they are done. Again, a not so good working example:

 1 class OuterElement extends HTMLElement {
 2   constructor() {
 3     super();
 4     console.log('outer ctor');
 5   }
 6 
 7   connectedCallback() {
 8     console.log('outer render');
 9     this.innerHTML = '<h1>Hello Web Component</h1>' +
10                       this.innerHTML +
11                      '<hr>';
12   }
13 
14 }
15 
16 class InnerElement extends HTMLElement {
17   constructor() {
18     super();
19     console.log('inner ctor');
20   }
21 
22   connectedCallback() {
23     console.log('inner render');
24     this.innerHTML = '<small>Inner Part</small>';
25   }
26 
27 }
28 
29 customElements.define('outer-element', OuterElement);
30 customElements.define('inner-element', InnerElement);

Let’s assume a piece of HTML like this:

1 <outer-element>
2   <inner-element></inner-element>
3 </outer-element>

The expected render output would be this one:

1 <h1>Hello Web Component</h1><small>Inner Part</small><hr>

If you execute this “as is”, the result is wrong, as shown in the Figure 2-4:

Look at the DOM, the <inner-element> comes after the <hr>, which is not what we expected.

So, how could we make the outer component to wait for all the children? Attaching events to the component itself wouldn’t be an option, because the content might be simple static text and a text node can’t trigger events.

Waiting for other custom elements would be easy. We could just loop through all outer elements, look weather they have a specific state and wait. Also, to make it easier to handle, the render method could be async. But in case of regular HTML and static text this will not work. One proposal is to set an explicit trigger for the render part:

1 <outer-element>
2   Static Text Before
3   <inner-element></inner-element>
4   Static Text After
5   <content-done />
6 </outer-element>

The element <content-done /> is such a trigger. Once it occurred it will call the render method of the outer-most element. The whole code is in the next example (Listing 2-11).

 1 class OuterElement extends HTMLElement {
 2   constructor() {
 3     super();
 4     console.log('outer ctor');
 5   }
 6 
 7   async connectedCallback() {
 8     console.log('outer render');
 9   }
10 
11   render() {
12     console.log('ready to go');
13     this.innerHTML = '<h1>Hello Web Component</h1>' +
14                       this.innerHTML +
15                      '<hr>';
16   }
17 
18 }
19 
20 class InnerElement extends HTMLElement {
21   constructor() {
22     super();
23     console.log('inner ctor');
24   }
25 
26   connectedCallback() {
27     console.log('inner render');
28     this.innerHTML = '<small>Inner Part</small>';
29   }
30 
31 }
32 
33 customElements.define('outer-element', OuterElement);
34 customElements.define('inner-element', InnerElement);
35 
36 // the currently needed utility
37 customElements.define('content-done', class extends HTMLElement {
38   connectedCallback() {
39     const {parentElement} = this;
40     parentElement.removeChild(this);
41     if (parentElement.render) {
42       parentElement.render();
43     }
44   }
45 });

There are two critical parts here. First, the outer-most element must be prepared to receive a call. In the example shown above it’s the custom render method. Second, the trigger element looks a bit awkward and is some context knowledge the template developer need to have; a thing we usually try to avoid.

If you watch carefully on the console output you see that the inner part is called twice. First, the immediate call from the render engine once the component is registered. Second, the call from the custom trigger element. While this seems in the demo not relevant, it could bring a serious performance penalty ones in a huge and more complex application.

If you have custom components only, this render approach is much more feasible.

<outer-element>
  <inner-element></inner-element>
</outer-element>

Here the <inner-element> could call render and if that happens for all elements it will work smoothly. You have just to test whether the content exists to let the inner most element render itself immediately. The @nyaf thin library shown in the appendix is doing exactly this, along with other libraries such as Polymer or Lightning.

An even better way is to wait for elements being available. That can be made by just delaying the component registration after document ready event.

 1 if (document.readyState === 'interactive'
 2 || document.readyState === 'complete') {
 3   customElements.define('outer-element', OuterElement);
 4   customElements.define('inner-element', InnerElement);
 5 } else {
 6   document.addEventListener('DOMContentLoaded', _ => {
 7     customElements.define('outer-element', OuterElement);
 8     customElements.define('inner-element', InnerElement);
 9   });
10 }

Here the code looks for an already available ready state or the finishing event.

This works very well for an application with a static appearance. However, if you have components loaded dynamically, as it happens in a Single Page App with a router logic, this will not work. The final (and best) solution depends on the kind of app you write and may change over time.

2.4 Customized Built-in Elements

New elements that we create, such as <time-format>, don’t have any associated semantics. They are unknown to search engines, and accessibility devices can’t handle them. Such things can be important, though. A search engine would be interested to know that we actually show a time. And if we’re making a special kind of button, why not reuse the existing <button> functionality?

We can extend and customize built-in HTML elements by inheriting from their classes. For example, buttons are instances of HTMLButtonElement. Extend HTMLButtonElement with a new class:

class HelloButton extends HTMLButtonElement {
  /* custom element methods */
}

Provide a third argument to customElements.define, that specifies the type to extend by using the tag’s name:

customElements.define('hello-button', HelloButton, {extends: 'button'});

There may be different tags that share the same DOM-class, that’s why specifying extends is needed. To get the custom element, insert a regular <button> tag, but add the is attribute to it like this:

<button is="hello-button">...</button>

Here’s a full example:

 1 <script>
 2 // The button that says "hello" on click
 3 class HelloButton extends HTMLButtonElement {
 4   constructor() {
 5     super();
 6     this.addEventListener('click', () => alert("Hello!"));
 7   }
 8 }
 9 
10 customElements.define('hello-button',
11                        HelloButton,
12                        {extends: 'button'});
13 </script>
14 
15 <button is="hello-button">Click me</button>
16 
17 <button is="hello-button" disabled>Disabled</button>

The new button extends the built-in one. That means it keeps the same styles and standard features like the disabled attribute.

If you prefer using the API, especially the document.createElement method, then you’ll find a second parameter that is an object with just one property, is.

let liComponent = document.createElement('ul', { is : 'app-list' })

The component itself must be registered as before, but now with the extension instruction:

customElements.define('app-list', ListComponent, { extends: "ul" });

That way you can modify any existing element and there is no need to create custom tags from scratch.

<ul is="app-list"></ul>

2.5 Advantage of TypeScript

In the previous examples I used only pure ES2015 code. The TypeScript syntax would be similar. However, using TypeScript’s features could make it even easier to handle certain tasks. One of the important parts is the handling of attributes. As already shown in the previous examples the observedAttributes method is responsible to trigger the observation. To access those attributes means calling methods like this.getAttribute('name'). And here lies a culprit. The usage of strings is error-prone. A much better way would it if we could use named properties, like this.name.

Using Generics

The key is a generic. In TypeScript you can assign a type to a concrete type placeholder to achieve this. However, a full implementation is quite tricky and it would be nice if we can handle this internally and not bother the developer with all the details. Let’s work this out step by step.

The component shall finally look like this:

 1 class TimeFormat extends BaseComponent<TimeProperties> {
 2 
 3   constructor() {
 4     super();
 5   }
 6 
 7   render() {
 8     let date = new Date(this.data.datetime
 9                 || Date.now());
10 
11     this.innerHTML = new Intl.DateTimeFormat("default", {
12       year: this.data.year || undefined,
13       month: this.data.month || undefined,
14       day: this.data.day || undefined,
15       hour: this.data.hour || undefined,
16       minute: this.data.minute || undefined,
17       second: this.data.second || undefined,
18       timeZoneName: this.data['time-zone-name']
19                  || undefined,
20     }).format(date);
21   }
22 
23   connectedCallback() {
24     this.render();
25   }
26 
27 }

As you can see the getAttribute calls are replaced by this.data calls that Intellisense understands through the generic of the base class BaseComponent. However, this will not work, because the generic is stripped out be the TypeScript transpiler and JavaScript doesn’t understand that. To get the type at runtime we need an instance of TimeProperties. The first decision to make is the type itself. It must be class, because we need a runtime instance. An interface would not work here. So let’s get the class:

class TimeProperties {
  datetime: string = '';
  year: string = '';
  month: string = '';
  day: string = '';
  hour: string = '';
  minute: string = '';
  second: string = '';
  'time-zone-name': string = '';
}

Then, we need to configure the base class. This involves two steps. First, the assignment of the generic type to the property data. This is primarily for a convenient access. Second, a method that retrieves the properties of the TimeProperties class and returns them as an array that observedAttributes can handle. The difficult part here is, and that’s the point where the coding can going to be a bit weird, that this method is static while on the component we work with an instance. Static members are being initialized before instance members, and especially before the constructor get called. Unfortunately TypeScript does not really have an elegant way to provide this, so we mix in some JavaScript here. The result is a base class as shown next:

 1 abstract class BaseComponent<T extends object>
 2          extends HTMLElement {
 3 
 4   private static _keys: any;
 5   private _data: T;
 6 
 7   constructor() {
 8     super();
 9     this._data = {} as T;
10   }
11 
12   public get data(): T {
13     return this._data;
14   }
15 
16   static get observedAttributes() {
17     return (this.constructor as any)._keys || [];
18   }
19 
20   attributeChangedCallback(name: string,
21                            oldValue: any,
22                            newValue: any) {
23     if (oldValue !== newValue) {
24       (this.data as any)[name] = newValue;
25     }
26     this.render();
27   }
28 
29   public abstract render(): void;
30 
31 }

The class is abstract to enforces the implementation. It’s generic as we planned it. It extends the usual HTMLElement class to make a real Web component. The crucial part is the call to get the array of properties: return (this.constructor as any)._keys (line 17). Here we access the constructor object, that’s available in the static initialization phase. But how we add the data at runtime to this property?

The trick is using a decorator. Decorators are a TypeScript feature that provides additional metadata to an object. They are static by definition and instantiated before the actual object. Technically they are just pure function calls, so we can do anything within the decorator. Decorators will become part of ECMAScript sooner or later (currently it’s experimental), but due to the polyfill the TypeScript compiler creates it’s no risk using them. The head of the class would now look like this:

1 @Observes(TimeProperties)
2 class TimeFormat extends BaseComponent<TimeProperties> {
3   // content omitted for brevity
4 }

The decorator Observes is defined like this:

 1 type Type<T> = new (...args: any[]) => T;
 2 
 3 function Observes<T extends {}>(type: Type<T>) {
 4   // the original decorator
 5   function internal(target: Object): void {
 6     Object.defineProperty(target.constructor, '_keys', {
 7       get: function () {
 8         const defaults = new type()
 9         return Object.keys(defaults);
10       },
11       enumerable: false,
12       configurable: false
13     });
14   }
15 
16   // return the decorator
17   return internal;
18 }

The inner part defines where the decorator is allowed to appear. The given signature (line 5) is for a class. The class definition itself is delivered by the infrastructure through the target parameter. On that object (internally it’s a Function object) we create a dynamic property. An instance property would go to target directly, while a static property goes to constructor. Pure JavaScript magic, by the way. The strategy has nothing to do with Web components nor TypeScript. To avoid TypeScript from complaining a helper type is created, called Type<T>. This helper defines a constructor signature to allow the code to create an actual instance (new type()). And on this actual type we can call Object.keys to get all the property names.

You have seen that the property class has initializers for the members (datetime: string = ‘’;) That’s necessary, because otherwise the TypeScript transpiler would strip this code out to make a smaller bundle and assume that JavaScript can handle this (it cans), but here we really need values at runtime and hence the initializers enforce the existence of the properties. The actual values doesn’t matter, as long as you don’t need any defaults.

Summary

That might sound complicated and seems to contradict the simplicity of easy to use Web components. But the effort to create a base class is only a one time task and its usage is a lot more easier afterwards.

Figure 2-6 shows the example with a typed base interface from the type library and additional comments on the property year. The editor is now able to help a lot while selecting the right property. That’s the main reason for the effort, because on the long term it will increase the code quality.

3 Shadow DOM

The Shadow DOM brings encapsulation. It allows a component to have its very own DOM tree, that can’t be accidentally accessed from the main document, may have local style rules, and more. When creating a new component, the component’s developer doesn’t need to know anything about the application this particular component is running in. That further simplifies the development.

3.1 Preparation

To recap some of the facts shown here, it’s recommended to have the Chrome browser available. To deal with the Shadow DOM, just activate the appropriate feature (see Figure 3-1) in Dev Tools settings (F12) and you’re good to go.

3.2 Built-in Shadow DOM

Complex browser controls are created and styled internally in different ways. Let’s have a look into <input type="range"> as an example. The browser uses DOM/CSS internally to draw them. That DOM structure is normally hidden from the developer, but we can see it in the developer tools with the Shadow DOM option enabled as mentioned before.

Then <input type="range"> looks like shown in Figure 3-2:

What you see under #shadow-root is called “shadow DOM”. It’s a piece of completely isolated code, made with the standard techniques like HTML and CSS. We can’t get built-in shadow DOM elements by regular JavaScript calls or selectors. These are not regular children, but a powerful encapsulation technique.

In the example above, we can see an useful attribute -webkit-slider-runnable-track. It’s non-standard, in fact, it exists for historical reasons. We can use it style subelements with CSS like this:

1 <style>
2 /* make the slider track red */
3 input::-webkit-slider-runnable-track {
4   background: red;
5 }
6 </style>
7 
8 <input type="range">

Once again, this is a non-standard attribute. It’s specific to browsers using the Chromium engine. But a similar structure can be expected in all other engines, and sometimes it helps to achieve weird requirements.

Here, it’s just a primer to show that there is more under the hood. The Shadow DOM of a Web component is a way to work with encapsulation in a well defined way.

3.3 Shadow Tree

A DOM element can have two types of DOM sub-trees:

1. Light tree: a regular DOM sub-tree, made of HTML children. All sub-trees that we’ve seen so far were “light”.
2. Shadow tree: a hidden DOM sub-tree, not reflected in HTML, hidden from users eyes.

If an element has both, then the browser renders only the shadow tree. But we can setup a kind of composition between shadow and light trees as well. Some more details are explained in the chapter Slots.

Terms

There are a few terms here you should know:

1. Shadow Host: The host component
2. Shadow Root: The root of the partial tree that forms the shadow tree
3. Shadow DOM: An isolated DOM that contains the content of the tree
4. Shadow Boundary: The border around the whole thing, includes root and tree

The relations between these parts are shown in Figure 3-3.

The access to the inner DOM is the same as for the regular DOM, that means you can use the same methods to manipulate the content. The methods might return different values and access different parts of the page (or nothing at all), though.

Using Shadow Trees

The shadow tree can be used in custom elements to hide component internals and apply component-local styles. For example, this <show-hello> element hides its internal DOM in a shadow tree:

 1 <script>
 2 customElements.define('show-hello', class extends HTMLElement {
 3   connectedCallback() {
 4     const shadow = this.attachShadow({mode: 'open'});
 5     shadow.innerHTML = `<p>
 6       Hello, ${this.getAttribute('name')}
 7     </p>`;
 8   }
 9 });
10 </script>
11 
12 <show-hello name="Joerg"></show-hello>

Figure 3-4 shows how the resulting DOM looks in the Chrome dev tools. All the content is placed under “#shadow-root (open)” tag:

The call to this.attachShadow({mode: …}) creates a shadow tree. The options are “open” and “closed”, I’ll explain this shortly.

Limitations

There are two limitations you have to consider:

1. We can create only one shadow root per component.
2. The component must be either a custom element or derive from one of these:

• <article>, represented through the API class HTMLArticleElement
• <aside>, represented through the API class HTMLAsideElement
• <blockquote>, represented through the API class HTMLBlockquoteElement
• <body>, represented through the API class HTMLBodyElement
• <div>, represented through the API class HTMLDivElement
• <footer>, represented through the API class HTMLFooterElement
• <h1…h6>, represented through the API class HTMLHeadElement
• <header>, represented through the API class HTMLHeaderElement
• <main>, represented through the API class HTMLMainElement
• <nav>, represented through the API class HTMLNavElement
• <p>, represented through the API class HTMLParagraphElement
• <section>, represented through the API class HTMLSectionElement
• <span>, represented through the API class HTMLSpanElement

Other elements, like <img>, can’t host a shadow tree. The basic rule is, that the element must be able to host some content at all.

Modes

The mode option sets the encapsulation level. It must have any of two values:

• “open” – the shadow root is available as this.shadowRoot. Any code (JavaScript) is able to access the shadow tree of the element.
• “closed” – this.shadowRoot is always null, and there is no access through code (sort of total isolation).

We can only access the shadow DOM by the reference returned by attachShadow (and probably hidden inside a class). Browser-native shadow trees, such as <input type="range">, are closed. There’s no way to access them.

The shadow root, returned by attachShadow, is like an element. We can use innerHTML or DOM methods, such as append, to populate it. In fact, the @nyaf thin library code uses innerHTML to assign the rendered content to the web component. As simple as it sounds as simple it is.

The element with a shadow root is called a “shadow tree host”, and is available as the shadow root host property. This will work only in “open” mode

var hostElement = elem.shadowRoot.host;

If you use this in a base class, it’s easy and powerful to copy data from host to shadow and back.

3.4 Encapsulation

The Shadow DOM is strongly delimited from the main document. Shadow DOM elements are not visible to querySelector from the light DOM. In particular, Shadow DOM elements may have identifiers that conflict with those in the light DOM. They must be unique only within the shadow tree. Also, the shadow DOM has own stylesheets. Style rules from the outer DOM don’t get applied, at least not directly. There are pseudo classes that help here to apply externally provided styles. You can find more about this in the chapter Styling.

An example shows how it works directly. First, a global styles is being created:

<style>
  p { color: red; }
</style>

Imagine a document, that contains that style and a web component definition:

 1 <div id="elem"></div>
 2 
 3 <script>
 4   const elem = this.querySelector('#elem');
 5   elem.attachShadow({mode: 'open'});
 6   elem.shadowRoot.innerHTML = `
 7     <style> p { font-weight: bold; } </style>
 8     <p>Hello, Joerg!</p>
 9   `;
10   console.log(document.querySelectorAll('p').length);
11   console.log(elem.shadowRoot.querySelectorAll('p').length);
12 </script>

Three effects can be recognized here:

1. The style from the document does not affect the shadow tree. The color is not red.
2. The style from the inside works. The element is bold.
3. To get elements in shadow tree, we must query from inside the tree (elem.shadowRoot).

In the example I use length to check for elements. If there is nothing the value would be ‘0’ and at runtime JavaScript treats this as false.

Shadow DOM without Components

Just as a side step it’s worth to mention that using Web components is not a condition for using the shadow DOM. You can create a shadow DOM on-the-fly without using Web components. Assume this regular HTML element:

<div id="shadowHost"></div>

Add some code to see how it creates the shadow DOM:

1 const shadow = document.querySelector('#shadowHost').createShadowRoot();
2 shadow.innerHTML = `
3   <p>Some text in the element.</p>
4   <style>p { color: red; border: 1px dashed; }</style>
5 `;

You now have an existing element upgraded with piece of isolated DOM and some content hidden form the rest of page (result in Figure 3-5).

Closing the Shadow Root

In all previous examples and in most examples in this book we use the open mode to attach a shadow root. If you really not need access to the root and have nothing to apply programmatically, consider closing the root by using closed.

const shadowroot = element.attachShadow({ mode: 'closed' });

In that case the element.shadowRoot returns null and obviously you can do nothing with it.

3.5 The Shadow Root API

The ShadowRoot interface of the Shadow DOM API is the root node of a DOM subtree that is rendered separately from a document’s main DOM tree. This is what you get with element.shadowRoot.

Properties

Some properties give access to the internal parts of a component.

• delegatesFocus: a readonly property, that returns a boolean that indicates whether delegatesFocus was set when the shadow was attached.
• host: a readonly property, that returns a reference to the DOM element the shadow root is attached to.
• innerHTML: Sets or returns a reference to the DOM tree inside the shadow root.
• mode: a readonly property, that returns the mode of the shadow root — either open or closed. This defines whether or not the shadow root’s internal features are accessible from JavaScript.

The ShadowRoot interface includes the following properties defined on the DocumentOrShadowRoot mixin. Note that this is currently only implemented by Chrome. Other browsers make this available in the Document.

• activeElement: a readonly property, that returns the Element within the shadow tree that has focus.
• styleSheets: a readonly property, that returns a StyleSheetList of CSSStyleSheet objects for stylesheets explicitly linked into, or embedded in a document.

Methods

Some methods extend this API.

• getSelection(): A method that returns a Selection object representing the range of text selected by the user, or the current position of the caret.
• elementFromPoint(): A method that returns the topmost element at the specified coordinates.
• elementsFromPoint(): A method that returns an array of all elements at the specified coordinates.
• caretPositionFromPoint(): A method that returns a CaretPosition object containing the DOM node containing the caret, and caret’s character offset within that node. The caret is the blinking point where the user starts typing.

Similar incompatibilities like for the properties appear when accessing these methods. This depends on browser version and manufacturer. Because the situation changes with each new version, it’s hard to give a clear advise here. Best is to first define what browsers with what version you need to support. Then have a look on MDN (Mozilla Developer Network) to look up any support issues and seek a polyfill to help solving compatibility issues.

3.6 Summary

In this chapter I covered the shadow DOM, the isolated inner part of a Web component. Several API calls are available to deal with the shadow DOM and it’s root element. You could also find examples how the shadow DOM looks like in a browsers development tool.

4 Events

The idea behind the shadow tree is to encapsulate internal implementation details of a component. That requires to expose events explicitly if you still want to interact with inner parts of a component.

Let’s say, a click event happens inside a shadow DOM of the <user-card> component. But scripts in the main document have no idea about the shadow DOM internals. So, to keep the details encapsulated, the browser has to re-targets the event. Events that happen in shadow DOM have the host element as the target, when caught outside of the component.

4.1 Events in ECMAScript

Before you deal with custom events you should have a basic understanding of the event schema in JavaScript.

Event Handlers

On the occurrence of an event, the application executes a set of related tasks. The block of code that achieves this purpose is called the event handler. Every HTML element has a set of events associated with it. We can define how the events will be processed in JavaScript by using event handlers. Sometimes the handler appears as a callback, a function that’s provided as a parameter. You can read the callback as the technical solution to create an event handler.

Assign a Handler

To assign a handler you have two options. First, an attribute on the HTML element. In that case the name starts with an on. For instance, the ‘click’ event is called onclick. Second, you can attach an event to an element object, using the HTML 5 API. In that case the pure name is used; ‘click’ remains ‘click’. Because we code Web components and deal with them as objects, you will usually use the second method exclusively. There is also a combination of both methods possible, where you assign the handler function to an event property. And these event properties are the same as the attribute (with an on prefix).

<button onclick="sendData()">Send Data</button>

const button = this.querySelector('button');
button.addEventListener('click', e => sendData(e));

const button = this.querySelector('button');
button.onclick = sendData;

Choose the Right Events

While the handling is not that difficult, choosing the right event is much harder. Of course, just using click sounds easy. But the sheer number of events is frightening.

HTML 5 Standard Events

The standard HTML 5 events are listed in the following table for your reference. The script indicates a JavaScript function to be executed against that event.

That list is probably not entirely complete, but shows the amazing number of events available. The second column is the category an event belongs to.

Event Bubbling

Event bubbling is a strange term but nonetheless very important. You can view an HTML page as a stack of layers. Each level of the document tree forms such a layer. If you have a document, and within this document is a <div> tag, than the div is on top of the document’s body. Than the lower layer is body and the upper layer is div. This three dimensional view of the otherwise flat document is helpful to understand the event handling. Assume that the user is clicking with the mouse onto the div element. We skip the operating system stuff here and capture only events already assigned to the browser’s window.

To get the bubbling right, it’s important to understand that the mouse event comes from the top. So it hits the div first. If there is a handler attached, it can be handled. Otherwise the event is forwarded to the next layer, in our example the document itself. This is called bubbling, because it looks like bubbles in bottle moving upwards until they hit something and crash. In the browser the bubbling goes even further:

Target -> Body -> HTML -> Document -> Window

If you have many elements on the page that form a deep hierarchy, then the bubbles have a long way through all of them. But this behavior is something you can control. The way upwards is technically called propagation. In the API of the event handler you get an event object. This object can be used to change the behavior by calling the stopPropagation method as shown here:

div.addEventListener("click", event => {
  event.stopPropagation();
});

The Event Object

The event object provides a lot information about the event. For example, the mouse events deliver the clicked mouse button and coordinates. The key events will obviously provide the actual key the user hit. Among these simple properties there are a few subtle ones.

Because the propagation may let bubble the event, it’s not entirely clear whether we are on the target directly or somewhere up the chain. That’s the reason we can capture the actual element using event.target. That’s the element that received the click or whatever. But the handler could be somewhere up (in direction of the document). This element is delivered using event.currentTarget. Imagine a list (<ul><li></ul>). Instead of attaching a handler to each list item, it’s much easier to just attach one to the whole list (ul). If the user clicks an item, the target is the li element, while currentTarget is ul. Though, quite often both properties deliver the same element.

After the bubbling phase the capturing phase starts. That means, each element on the bubble way will be informed that the event has been handled.

Stop Other Handlers

If an element has multiple event handlers on a single event, then even if one of them stops the bubbling, the other ones still execute. In other words, event.stopPropagation stops the move upwards, but on the current element all other handlers will run. To stop the bubbling and prevent handlers on the current element from running, there’s the method event.stopImmediatePropagation. After it no other handlers execute.

Other Types of Propagation

Event capturing is another type of event propagation. It is basically the way back to the event’s source.

Event Capturing

To turn event capturing on, pass true as the third argument to the addEventListener method.

Element.addEventListener("click", function(){}, true);

This type of propagation is rarely used. Instead of working from inner to outer it flips the direction and goes from outer to inner. Here is the hierarchy.

Window -> Document -> HTML -> Body -> Target

Internally the capturing phase precedes the bubbling phase. That’s sort of logical, because the operating system has no idea of the internal structure of your document. So it sends the mouse click to the browser window. That’s where the capture phase starts, silently and in the background until it hit’s an element that has a handler attached. Then the bubbling phase begins. That’s where we get aware of the event and start dealing with it.

Removing Handlers

To remove a handler just call event.removeEventListener with the same parameters you used for adding it. This can be done only in code, there is no way to remove a handler added in markup.

Multiple Handlers

You can attach multiple handlers and they execute in the order you assigned them. This can be done only in code, there is no way to add more than one handler in markup.

Stop Default Behavior

Several elements react to events out-of-the-box. For example, an anchor element will follow the href attribute on a mouse click. If you attached a handler, this private handler will execute first, but the internal behavior will happen afterwards. That can be very annoying if you have the handler to prevent this. To suppress this behavior, you call a method preventDefault(). You may have seen returning false from the event handler to achieve the same. But that’s an exception and is designed to support this behavior with the on[event] syntax. A handler attached directly in HTML doesn’t receive an event object. Without that, you wouldn’t be able to prevent anything. But, you can return false as a solution. In all other situations the return value is ignored.

Follow Up Events

Some events form chains. Let’s take keypress as an example. That’s a full key cycle. But before this event comes, you can receive a keydown and a keyup. A similar thing happens for click, that starts with mousedown, followed by mouseup. It’s important for the infrastructure to work that way, because the information is needed to detect, for example, a dblclick.

Passive Events

The optional passive: true option of addEventListener signals the browser that the handler is not going to call preventDefault(). That’s needed because there are some events like touchmove on mobile devices (when the user moves their finger across the screen), that cause scrolling by default, but that scrolling can be prevented using preventDefault(). When the browser detects such an event, it has first to process all handlers, and then if preventDefault is not called anywhere, it can proceed with scrolling. That may cause unnecessary delays in the UI. The option tells the browser that the handler is not going to cancel scrolling. Then browser scrolls immediately providing a maximally fluent experience, and the event is handled later on. Passive is true by default for touchstart and touchmove on most browsers.

Document Handlers

It’s quite often a good idea and sometimes it makes your life really easy, when you stop thinking in adding endless chains of handlers to a growing number of elements. Because the event bubbles anyway, it’s a solution to add few handlers (mouse, key, submit) to the document and just check the e.target property whether you got the right one. A clever approach is to use the dataSet property, reflected in HTML as data- attributes. Say, you want a button click handle something using a global handler:

 1 <button data-form-id="subscribe-mail" data-action-id="submit">
 2   Show Mail Form
 3 </button>
 4 
 5 <form id="subscribe-mail" hidden>
 6   Your mail: <input type="email">
 7 </form>
 8 
 9 <script>
10   document.addEventListener('click', function(event) {
11     let id = event.target.dataset.formId;
12     if (!id) return;
13     let elem = document.getElementById(id);
14     elem.hidden = !elem.hidden;
15     let action = event.target.dataset.actionId;
16     if (action) {
17       // add logic to submit the form
18     }
19   });
20 </script>

The event in this example is added to the document. Because it’s the underlying layer, it will receive all unhandled and propagated events. With just one handler you can handle all events globally. That could help write code that’s better to maintain.

4.2 Events in Web Components

Listing 4-2 shows a simple example with an event handler attached on the shadow DOM:

 1 <user-card></user-card>
 2 
 3 <script>
 4 customElements.define('user-card', class extends HTMLElement {
 5   connectedCallback() {
 6     this.attachShadow({mode: 'open'});
 7     this.shadowRoot.innerHTML = `<p>
 8       <button>Click me</button>
 9     </p>`;
10     this.shadowRoot.firstElementChild.onclick =
11       e => alert("Inner target: " + e.target.tagName);
12   }
13 });
14 
15 document.onclick =
16   e => alert("Outer target: " + e.target.tagName);
17 </script>

If you click on the button, the messages are:

• Inner target: BUTTON – internal event handler gets the correct target, the element inside shadow DOM.
• Outer target: USER-CARD – document event handler gets shadow host as the target.

Event re-targeting is a great thing to have, because the outer document doesn’t have to know about component internals. From its point of view, the event happened on <user-card>.

Events and Slots

Re-targeting does not occur if the event occurs on a slotted element, that physically lives in the light DOM. In the chapter about slots you can find more details regarding slot behavior. For example, if a user clicks on <span slot="username"> in the example below, the event target is exactly this span element, for both shadow and light handlers (Listing 4-3).

 1 <user-card id="userCard">
 2   <span slot="username">Joerg Krause</span>
 3 </user-card>
 4 
 5 <script>
 6 customElements.define('user-card', class extends HTMLElement {
 7   connectedCallback() {
 8     this.attachShadow({mode: 'open'});
 9     this.shadowRoot.innerHTML = `<div>
10       <b>Name:</b> <slot name="username"></slot>
11     </div>`;
12 
13     this.shadowRoot.firstElementChild.onclick =
14       e => alert("Inner target: " + e.target.tagName);
15   }
16 });
17 
18 userCard.onclick = e => alert(`Outer target: ${e.target.tagName}`);
19 </script>

If a click happens on “Joerg Krause”, for both inner and outer handlers the target is <span slot="username">. That’s an element from the light DOM, so no re-targeting.

On the other hand, if the click occurs on an element originating from shadow DOM, e.g. on <b>Name:</b>, then, as it bubbles out of the shadow DOM, its event.target property is reset to <user-card>.

Event Bubbling

For purposes of event bubbling, flattened DOM is used. So, if we have a slotted element, and an event occurs somewhere inside it, then it bubbles up to the <slot> and upwards.

The full path to the original event target, with all the shadow elements, can be obtained using event.composedPath(). As we can see from the name of the method, that path is taken after the composition.

In the example above, the flattened DOM is looking like this:

1 <user-card id="userCard">
2   #shadow-root
3     <div>
4       <b>Name:</b>
5       <slot name="username">
6         <span slot="username">Joerg Krause</span>
7       </slot>
8     </div>
9 </user-card>

So, for a click on <span slot="username">, a call to event.composedPath() returns an array:

[
  span,
  slot,
  div,
  shadow-root,
  user-card,
  body,
  html,
  document,
  window
]

That’s exactly the parent chain from the target element in the flattened DOM, after the composition.

That’s a similar principle as for other methods that work with shadow DOM. Internals of closed trees are completely hidden.

Composed Events

Most events successfully bubble through a shadow DOM boundary. There are few events that do not.

This is governed by the composed event object property. If it’s true, then the event does cross the boundary. Otherwise, it only can be caught from inside the shadow DOM.

If you take a look at UI Events specification, most events have composed: true:

• blur, focus, focusin, focusout
• click, dblclick
• mousedown, mouseup, mousemove, mouseout, mouseover
• wheel
• beforeinput, input, keydown, keyup

All touch events and pointer events also have composed: true.

There are some events that have composed: false though:

• mouseenter, mouseleave (they do not bubble at all)
• load, unload, abort, error
• select
• slotchange

These events can be caught only on elements within the same DOM, where the event target resides.

4.3 Custom Events

When we dispatch custom events, we need to set both bubbles and composed properties to true for it to bubble up and out of the component.

In Listing 4-4 I create div#inner in the shadow DOM of div#outer and trigger two events on it. Only the one with composed: true makes it outside to the document.

 1 <div id="outer"></div>
 2 
 3 <script>
 4 outer.attachShadow({mode: 'open'});
 5 
 6 let inner = document.createElement('div');
 7 outer.shadowRoot.append(inner);
 8 
 9 document.addEventListener('test', event => alert(event.detail));
10 
11 inner.dispatchEvent(new CustomEvent('test', {
12   bubbles: true,
13   composed: true,
14   detail: "composed"
15 }));
16 
17 inner.dispatchEvent(new CustomEvent('test', {
18   bubbles: true,
19   composed: false,
20   detail: "not composed"
21 }));
22 </script>

The structure internally looks like this:

1 div(id=outer)
2   #shadow-dom
3     div(id=inner)

The dispatchEvent API

In the last example I used the dispatchEvent API. It dispatches an event on a target. The listeners are invoked synchronously in there appropriate order. The normal event processing rules apply. An outside viewer can not distinguish between such custom events and those fired by the internal parts of the document. The “event” itself is described by an interface and exists as an instantiable class with the same name. If you work with TypeScript, you have the type and can make instances like this:

1 const evt = new Event("look", {"bubbles":true, "cancelable":false});
2 document.dispatchEvent(evt);

The options dictionary is of type EventInit, with just the three already mentioned properties:

• bubbles: An optional Boolean indicating whether the event bubbles. The default is false.
• cancelable: An optional Boolean indicating whether the event can be cancelled. The default is false.
• composed: An optional Boolean indicating whether the event will trigger listeners outside of a shadow root. The default is false.

In TypeScript the definition looks like this:

 1 interface EventInit {
 2     bubbles?: boolean;
 3     cancelable?: boolean;
 4     composed?: boolean;
 5 }
 6 
 7 interface Event {
 8     readonly bubbles: boolean;
 9     cancelBubble: boolean;
10     readonly cancelable: boolean;
11     readonly composed: boolean;
12     readonly currentTarget: EventTarget | null;
13     readonly defaultPrevented: boolean;
14     readonly eventPhase: number;
15     readonly isTrusted: boolean;
16     returnValue: boolean;
17     /** deprecated (only for old browsers) */
18     readonly srcElement: EventTarget | null;
19     readonly target: EventTarget | null;
20     readonly timeStamp: number;
21     readonly type: string;
22     composedPath(): EventTarget[];
23     initEvent(
24       type: string,
25       bubbles?: boolean,
26       cancelable?: boolean): void;
27     preventDefault(): void;
28     stopImmediatePropagation(): void;
29     stopPropagation(): void;
30     readonly AT_TARGET: number;
31     readonly BUBBLING_PHASE: number;
32     readonly CAPTURING_PHASE: number;
33     readonly NONE: number;
34 }
35 
36 declare var Event: {
37     prototype: Event;
38     new(type: string, eventInitDict?: EventInit): Event;
39     readonly AT_TARGET: number;
40     readonly BUBBLING_PHASE: number;
41     readonly CAPTURING_PHASE: number;
42     readonly NONE: number;
43 };

Customize Events

Apart from the common Event interface there is another type you can use: CustomEvent. Despite the name you don’t need to use it to fire a custom event, but it’s often helpful to get a clearer information about the nature of the event. The only difference is that CustomEvent provides abn additional property called detail. This is an object you define on the source and the receiver can get custom data here. The sheer existence clarifies the custom nature of the event. The option is part of the initializer, now named CustomEventInit.

 1 // this.process omitted for brevity
 2 obj.addEventListener("loop", (e) => { this.process(e.detail) });
 3 
 4 // create and dispatch the event
 5 var event = new CustomEvent("loop", {
 6   detail: {
 7     loops: 100
 8   }
 9 });
10 obj.dispatchEvent(event);

The CustomEventInit type accepts all properties from EventInit, too.

In TypeScript the definition looks like this:

 1 interface CustomEventInit<T = any> extends EventInit {
 2     detail?: T;
 3 }
 4 
 5 interface CustomEvent<T = any> extends Event {
 6     readonly detail: T;
 7     initCustomEvent(
 8       typeArg: string,
 9       canBubbleArg: boolean,
10       cancelableArg: boolean,
11       detailArg: T): void;
12 }
13 
14 declare var CustomEvent: {
15     prototype: CustomEvent;
16     new<T>(
17       typeArg: string,
18       eventInitDict?: CustomEventInit<T>): CustomEvent<T>;
19 };

This provides both, a type definition and a constructor description.

4.4 Smart Events

Adding events requires script work. To make it easier to use, some global code could be helpful. However, this doesn’t change the basic behavior and flow as described before. Events are defined by a special instruction. They are attached to document object, regardless the usage.

Events are easy to add directly using a dataset like data-onclick. All JavaScript events are supported that way. Just replace ‘onclick’ in the example with any other JavaScript event.

<button data-on-click="clickId">OK</button>

Now, on an applications global start script (see Listing 4-5), attach handlers to anything with such an event definition.

{ format: js, caption: “Listing 4-5: Smart Events (chapter4/smart/index.html)”

 1 document.querySelectorAll('[^data-on-]').forEach(elem => {
 2   const events = elem.dataSet.filter(d => d.startsWidth('on'));
 3   events.forEach(event =>  {
 4     elem.addEventHandler(event, e => {
 5       // global handler
 6       const instruction = e.target.dataSet(event);
 7       // deal with it
 8     });
 9   })
10 })

The effect here is – depending on the number of such events – to drastic reduce the amount of code for attaching events. However, it’s not that easy to add similar removeEventHandler calls. The code is more appropriate for a single page app, where the final state of the code is static and held in memory anyway.

4.5 Summary

In this chapter I explained the event handling in the browser, the way we attach events to normal and shadowed web components and how to extend the event system. Using custom events the way component communicate to each other can be easily extended. Some TypeScript definitions show how the objects are built internally. Attaching events globally using the document object shows finally how to minimize the effort to attach mulitple events.

5 Templates

The concept of templates is a fundamental part of almost all web development environments. Examples for server side template languages are something like Razor (.NET), Haml (Ruby), Django (Python), Pug (NodeJS) and Smarty (PHP). Examples for client side template languages can be found in Angular and many more frameworks.

Templates help creating dynamic parts, reduce boilerplate code, avoid repeating markup. The raise of so many template variants in Web frameworks, client and server side, was forced by a missing alternative in HTML. That changed dramatically with the WhatWG HTML Template Specification. HTML Templates still struggle to be widely accepted, but with the usage in Web components they find their way back into the light.

5.1 HTML 5 Templates

A built-in <template> element serves as a storage for HTML markup templates. The browser ignores it contents, only checks for syntax validity, but we can access and use it in JavaScript, to create or enhance other elements. All modern browsers support this, but to ensure it’s really full supported you may consider a small test.

1 function hasTemplateSupport() {
2   return 'content' in document.createElement('template');
3 }
4 
5 if (hasTemplateSupport()) {
6   // Use it
7 } else {
8   // Fall back to a library
9 }

How it Works

In theory, we could create any invisible element somewhere in HTML for HTML markup storage purposes. The special thing about <template> is the nature of being cloneable. The content can be any valid HTML, even if it normally requires a proper enclosing tag.

For example, we can put there a table row <tr>:

1 <template>
2   <tr>
3     <td>Contents</td>
4   </tr>
5 </template>

Usually, if we try to put <tr> inside, say, a <div>, the browser detects the invalid DOM structure and “fixes” it, adds <table> around. That’s not what we want. On the other hand, <template> keeps exactly what we place there.

We can put styles and scripts into <template> as well:

1 <template>
2   <style>
3     p { font-weight: bold; }
4   </style>
5   <script>
6     alert("Hello");
7   </script>
8 </template>

The browser considers <template> content “out of the document”. Hence, styles are not applied, scripts are not executed, autoplay of a video element is not run, and much more. Technically it’s inert until activated. The content becomes live (styles apply, scripts run and so on), when it’s being inserted into the document. Also the access from outside, using querySelector or other API calls, will not see the template’s content.

You may ask where to place the <template> element, if it isn’t part of the document anyway. The answer is: It doesn’t matter. It may appear in the <head> element or somewhere in the body among other elements. It depends on the actual content, where it makes more sense. Global templates might be better placed in the head, while a row template for some table is probably easier to handle within the table itself.

5.2 Activating a Template

The template content is available in its content property as a DocumentFragment – a special type of DOM node. We can treat it as any other DOM node, except one special property. We don’t insert the template itself, but instead its children, available through the property content. The example in Listing 5-1 shows how to use.

 1 <template id="tmpl">
 2   <script>
 3     alert("Hello");
 4   </script>
 5   <div class="message">Hello, template!</div>
 6 </template>
 7 
 8 <script>
 9   let elem = document.createElement('div');
10   elem.append(tmpl.content.cloneNode(true));
11   document.body.append(elem);
12 </script>

The interesting part here is, that you doesn’t need to select the template. Based on it’s id property it’s already available as a global property. That means tmpl.content is available after the browser has parsed the document and there is no need to query the element explicitly. If you would query (document.querySelector('#tmpl')) the result would be exactly the same. The result is shown in Figure 5-1.

Clone or Import

There are several methods to clone or import nodes. You need a deep copy, but apart from this it’s really up to you. One method is importNode while the other is cloneNode. Historically the importNode method was made to copy content from one document to the other. You may see the template with its document fragment as such a node source and the actual document as the node sink. But technically it’s a clone operation and here the cloneNode method seems more appropriate. However, it’s academical, because both method lead to exactly the same result. Modern browsers doesn’t distinguish here anymore in relation to templates. However, of you read out the ownerDocument property, it could have a different value when using importNode. Let’s rewrite the last example to show the difference:

 1 <template id="tmpl">
 2   <script>
 3     alert("Hello");
 4   </script>
 5   <div class="message">Hello, template!</div>
 6 </template>
 7 
 8 <script>
 9   let elem = document.createElement('div');
10   elem.append(document.importNode(tmpl.content, true));
11   document.body.append(elem);
12 </script>

I, personally, found the cloneNode way more intuitiv and easier to read. But it may depend on the real code whether other options suit better.

5.3 Templates and Web Components

Templates play a crucial role in Web components. It’s a fundamental part to create powerful components. The main purpose is to handle the Shadow DOM properly, either as part of a component or somewhere directly in the DOM.

Shadow DOM

Let’s create a Shadow DOM example using the <template> element:

 1 <template id="tmpl">
 2   <style> p { font-weight: bold; } </style>
 3   <p id="message"></p>
 4 </template>
 5 
 6 <div id="elem">Click me</div>
 7 
 8 <script>
 9   elem.onclick = function() {
10     elem.attachShadow({mode: 'open'});
11     elem.shadowRoot.append(tmpl.content.cloneNode(true));
12     elem.shadowRoot.getElementById('message').innerHTML = "Hello Shadow!";
13   };
14 </script>

Figure 5-2 shows the result in the browser’s developer tools.

In line 10 when we clone and insert tmpl.content, and instead its DocumentFragment, its children <style>, <p> are inserted. They form the shadow DOM, then.

Shadow DOM and innerHTML

After the initial decision to use the Shadow DOM the next question is how to get content in there. If the template isn’t your concern you may end up with something like this:

1 <div id="host"></div>
2 <script>
3   var elem = document.querySelector('#host');
4   elem.attachShadow({ mode: 'open' });
5   elem.shadowRoot.innerHTML = '<span>Host node</span>';
6 </script>

That’s fine for smaller examples. But using string for HTML is a way to mess up things for sure. If you can’t switch to a template engine such as JSX or import the HTML from documents, using the <template> element is the better way to go.

1 <div id="host"></div>
2 <template id="tmpl">
3   <span>Host node</span>
4 </template>
5 <script>
6   var elem = document.querySelector('#host');
7   elem.attachShadow({ mode: 'open' });
8   elem.shadowRoot.appendChild(tmpl.content.cloneNode(true));
9 </script>

5.4 Nested Templates

Consider the example in Listing 5-6 with a template inside another template.

1 <template id="section">
2   <h1>Header</h1>
3   <p>Text</p>
4   <template id="details">
5     <h1>Addition</h1>
6     <p>Details</p>
7   </template>
8 </template>

While this is allowed to do, the activation is not so simple. The inner template remains inert even if the outer is properly activated. You need to activate both, separately. That’s not a big effort but tricky in all the details.

1 const elem = document.querySelector('#host');
2 const outer = section.content.cloneNode(true);
3 const inner = outer.children.details;
4 outer.removeChild(inner);
5 outer.appendChild(inner.content.cloneNode(true));
6 elem.appendChild(outer);

Whether you work with or without Shadow DOM doesn’t matter. For the sake of clarity the example in Listing 5-7 goes straight. First, the outer template is pulled using the magic property section that corresponds to the templates id property (line 2). Then it’s cloned. The clone has a collection of children, among them is the inner template. Even here you can use the magic property, called details according to the inner template’s id (line 3). Because the deep clone with cloneNode will also clone the inner template we are going to remove it (line 4). It’s not really disturbing, but, you know, we love clean code. Hence we clone the inner part, add it to the outer clone (line 5) and attach the whole construct to the real DOM (line 6).

Making inner templates invisible to the first layer allows us to keep the template structure clean and readable.

5.5 Template Styles

Styles in templates behave like any other style. A style node can be copied like any other node. But you can also access the host element by using the pseudo selector :host. More about this can be found in the chapter Shadow DOM Styling.

Apply Global Styles

The following example takes care of the template behavior. It uses the template element if needed to create a shadow DOM. It’s the regular creation of a shadowed web component using a separate method. It’s not complete for the sake of brevity, but it shows the idea.

 1 protected setup() {
 2   if ((<any>this.constructor).withShadow) {
 3     const template = document.createElement('template');
 4     template.innerHTML = this.render();
 5     if (!this.shadowRoot || this.shadowRoot.mode === 'closed') {
 6       this.attachShadow({ mode: 'open' });
 7       // copy styles to shadow if shadowed and there is something to add
 8       if (this.copyStyles) {
 9         const style = document.createElement('style');
10         style.textContent = this.globalStyles;
11         this.shadowRoot.appendChild(style);
12       }
13       this.shadowRoot.appendChild(template.content.cloneNode(true));
14     }
15   } else {
16     this.innerHTML = this.render();
17   }
18 }

The property this.copyStyles provides a Boolean value to control the behavior. Assume it’s an observed attribute to control a components behavior from the usage side. If it’s true the setup code create a style element and copies some prepared styles into this. That works even with plain text. The property this.globalStyles is this source. Either it’s provided as an attribute, too. Or you setup some code in the web components constructor to copy all global styles in one step. That would bring both, isolation and global style access. Not always the ideal solution, but often a quick win for complex CSS frameworks.

Copying global styles could look like this:

 1 for (let i = 0; i < this.ownerDocument.styleSheets.length; i++) {
 2   const css = this.ownerDocument.styleSheets[i] as CSSStyleSheet;
 3   try {
 4     if (!css.rules || css.rules.length === 0) {
 5       continue;
 6     }
 7     this.globalStyles += Object.keys(css.cssRules)
 8       .map(k => css.cssRules[k].cssText ?? ' ')
 9       .join(' ');
10   } catch(err) {
11     console.warn(err);
12   }
13 }

Place this in the component’s constructor. If you do this for multiple documents consider making the property this.globalStyles static, check for already copied styles and skip the code if it’s already there. Then the first component enhanced in such a way pulls the styles and all others in your document benefit silently.

5.6 Summary

In this chapter you learned about templates and how you can use them with or without web components. I also captured the usagwe of templates with slots, nested templates, and how to deal with styles.

6 Slots

A slot is a placeholder that users can fill with their own markup. The slot may exist outside a Web component or inside, in conjunction with a template or Shadow DOM (or both).

6.1 Slots Explained

Many types of components, such as tabs, menus, image galleries, and so on, need content to render properly.

Just like a browser’s built-in element <select> expects <option> items, a <custom-tabs> may expect the actual tab content to be passed. And a <custom-menu> may expect menu items.

The code that makes use of <custom-menu> could look like this:

1 <custom-menu>
2   <title>Languages</title>
3   <menu-item>JavaScript</menu-item>
4   <menu-item>PHP</menu-item>
5   <menu-item>Ruby</menu-item>
6 </custom-menu>

Then our component should render it properly, as a nice menu with given title and items, handle menu events, etc.

Slot and Templates

Thw following example shows a shadowed template with some neat styling.

 1 <template id="tmpl">
 2   <style>
 3     :host {
 4       background: #f8f8f8;
 5       padding: 10px;
 6       transition: all 400ms ease-in-out;
 7       box-sizing: border-box;
 8       border-radius: 5px;
 9       width: 450px;
10       max-width: 100%;
11     }
12     :host(:hover) {
13       background: #ccc;
14     }
15     div {
16       position: relative;
17     }
18     header {
19       padding: 5px;
20       border-bottom: 1px solid #aaa;
21     }
22     h3 {
23       margin: 0 !important;
24     }
25     textarea {
26       font-family: inherit;
27       width: 100%;
28       height: 100px;
29       box-sizing: border-box;
30       border: 1px solid #aaa;
31     }
32     footer {
33       position: absolute;
34       bottom: 10px;
35       right: 5px;
36     }
37   </style>
38   <div>
39     <header>
40       <h3>Add a Comment</h3>
41     </header>
42     <slot name="p"></slot>
43     <textarea></textarea>
44     <footer>
45       <button>Post</button>
46     </footer>
47   </div>
48 </template>
49 <div id="host">
50   <p slot="p">Instructions go here</p>
51 </div>
52 
53 <script>
54   var shadow = document.querySelector('#host');
55   shadow.attachShadow({ mode: 'open' });
56   shadow.shadowRoot.appendChild(tmpl.content.cloneNode(true));
57 </script>

The idea was here to provide some initial instruction to make the template more dynamic. The slot is some kind of parameter here: <slot name="p"></slot> (line 42).

The name attribute is a reference to the element that has a slot attribute with that name. That’s the way to get external information in the template at runtime. The result is shown in Figure 6-1.

Shadow DOM

The Shadow DOM supports <slot> elements, that are automatically filled by the content from light DOM. The above example is already “shadowed”, but that’s just an option. There is no need for the slots to use a Shadow DOM.

6.2 Slots and Components

Let’s see how slots work on a simple example with Web Components. Here, the <user-card> shadow DOM provides two slots, filled from light DOM:

 1 <user-card>
 2   <span slot="username">Joerg</span>
 3   <span slot="birthday">May, 26</span>
 4 </user-card>
 5 <script>
 6 customElements.define('user-card', class extends HTMLElement {
 7   connectedCallback() {
 8     this.attachShadow({mode: 'open'});
 9     this.shadowRoot.innerHTML = `
10       <div>Name:
11         <slot name="username"></slot>
12       </div>
13       <div>Birthday:
14         <slot name="birthday"></slot>
15       </div>
16     `;
17   }
18 });
19 </script>

Then the browser performs “composition”: it takes elements from the light DOM and renders them in corresponding slots of the shadow DOM. At the end, we have exactly what we want – a component that can be filled with data.

Figure 6-2 shows the DOM structure after the script, not taking composition into account.

The shadow DOM is under #shadow-root. For rendering purposes, for each <slot name="..."> in shadow DOM, the browser looks for slot=”…” with the same name in the light DOM. These elements are rendered inside the slots. The flattened DOM exists only for rendering and event-handling purposes. It’s kind of “virtual”. That’s how things are shown. But the nodes in the document are actually not moved around!

The last proposition can be easily checked if we run querySelectorAll. All the nodes are still at their places. The example shows that the light DOM <span> nodes are still at the same place, under <user-card>. Check it by executing this piece of code:

// Expected output: 2
console.log(document.querySelectorAll('user-card span').length );

So, the flattened DOM is derived from shadow DOM by inserting slots. The browser renders it and uses it for style inheritance, and event propagation. But JavaScript’s DOM API still sees the document “as is”, before flattening.

6.3 Slot Behavior

In this section I go a little deeper in the specific behaviors of slots.

Slot Positions

Only top-level children may have slot=”…” attribute. The slot=”…” attribute is only valid for direct children of the shadow host (in our example, <user-card> element). For nested elements it’s ignored.

In the example shown in Listing 6-3 the second <span> here is ignored (as it’s not a top-level child of <user-card>).

1 <user-card>
2   <span slot="username">Joerg Krause</span>
3   <div>
4     <!-- invalid slot, must be direct child of user-card -->
5     <span slot="birthday">May, 26</span>
6   </div>
7 </user-card>

Multiple Slots

If there are multiple elements in light DOM with the same slot name, they are appended into the slot, one after another. The next example shows this and makes use of a list created by repeating slots.

 1 <user-card>
 2   <li slot="username">Joerg</li>
 3   <li slot="username">Clemens</li>
 4   <li slot="username">Elest</li>
 5   <span slot="birthday">May, 26</span>
 6 </user-card>
 7 <script>
 8   customElements.define(
 9     'user-card',
10     class extends HTMLElement {
11       connectedCallback() {
12         this.attachShadow({ mode: 'open' });
13         this.shadowRoot.innerHTML = `
14         <div>Name:
15           <ul>
16             <slot name="username"></slot>
17           </ul>
18         </div>
19         <div>Birthday:
20           <slot name="birthday"></slot>
21         </div>`;
22       }
23     }
24   );

However, the user must know that slot’s provided as <li> are appropriate here. That’s some sort of context knowledge that contradicts the abstraction idea behind templates and slots. To avoid this, additional code in the component is required. Also, the very primitive way to work with innerHTML is obviously not the best idea.

6.4 Slot Fallback Content

If we put something inside a <slot>, it becomes the fallback, “default” content. The browser shows it if there’s no corresponding filler in light DOM.

Listing 6-5 shows in this piece of shadow DOM, that it renders anonymous if there’s no slot=”username” in light DOM.

 1 <user-card></user-card>
 2 <script>
 3   customElements.define(
 4     'user-card',
 5     class extends HTMLElement {
 6       connectedCallback() {
 7         this.attachShadow({ mode: 'open' });
 8         this.shadowRoot.innerHTML = `
 9       <div>Name:
10         <slot name="username">Not available</slot>
11       </div>
12       <div>Birthday:
13         <slot name="birthday">n/a</slot>
14       </div>
15     `;
16       }
17     }
18   );
19 </script>

The <user-card> element is empty, so all slot content falls back to default text provided in the slots’ definitions.

Figure 6-4 shows the outcome in the browser and debug view.

6.5 Default Slots

The first <slot> in shadow DOM that doesn’t have a name is a “default” slot. It gets all nodes from the light DOM that aren’t slotted elsewhere.

For example, let’s add the default slot to our <user-card> that shows all unslotted information about the user:

 1 <user-card>
 2   <div>I like to read...</div>
 3   <span slot="username">Joerg Krause</span>
 4   <span slot="birthday">May, 26</span>
 5   <div>...and play golf too!</div>
 6 </user-card>
 7 <script>
 8 customElements.define('user-card', class extends HTMLElement {
 9   connectedCallback() {
10     this.attachShadow({mode: 'open'});
11     this.shadowRoot.innerHTML = `
12     <div>Name:
13       <slot name="username"></slot>
14     </div>
15     <div>Birthday:
16       <slot name="birthday"></slot>
17     </div>
18     <fieldset>
19       <legend>Other information</legend>
20       <slot></slot>
21     </fieldset>
22     `;
23   }
24 });
25 </script>

All the unslotted light DOM content gets into the “Other information” fieldset (line 20).

Elements are appended to a slot one after another (see Figure 6-5), so both unslotted pieces of information are in the default slot together. The named slots are stripped out and placed where the placeholders are as before.

6.6 Slot Events

Now let’s go back to the element<custom-menu>, mentioned at the beginning of this chapter. We can use slots to distribute menu items. Here’s the markup for <custom-menu>:

1 <custom-menu>
2   <span slot="title">Technologies</span>
3   <menu-item slot="item">HTML 5</menu-item>
4   <menu-item slot="item">CSS 3</menu-item>
5   <menu-item slot="item">ECMAScript</menu-item>
6 </custom-menu>

That’s much better than the generic <li> in the slot elements. It requires, however, an additional component. The code has now two components:

 1 customElements.define(
 2   'menu-item',
 3   class extends HTMLElement {
 4     connectedCallback() {
 5       this.attachShadow({ mode: 'open' });
 6       this.shadowRoot.innerHTML = `<li>${this.textContent}</li>`;
 7     }
 8   }
 9 );
10 customElements.define(
11   'custom-menu',
12   class extends HTMLElement {
13     connectedCallback() {
14       this.attachShadow({ mode: 'open' });
15       this.shadowRoot.innerHTML = `
16     <div>
17       <slot name="title"></div>
18       <ul>
19         <slot name="item"></slot>
20       </ul>
21     </div>
22 `;
23     }
24   }
25 );

The slots’ content is not further abstracted, instead, it’s pulled directly as text using the textContent property.

Add Event Handler

As it is a menu, we need to add as a last step adding event handlers. That’s not so much different from regular HTML, with just one exception. Attached event handlers are not copied in the clone process. Because slots need templates and templates need clone, it means that we must attach the events in the component and expose the event.

To expose custom events we use the API call dispatchEvent like this:

 1 customElements.define(
 2   'menu-item',
 3   class extends HTMLElement {
 4     connectedCallback() {
 5       this.attachShadow({ mode: 'open' });
 6       this.shadowRoot.innerHTML = `<li>${this.textContent}</li>`;
 7       this.shadowRoot.addEventListener('click', (e) => {
 8         if (e.target.tagName === 'LI') {
 9           console.log(e);
10           this.dispatchEvent(new CustomEvent('menuclick', {
11             details: e.currentTarget.textContent
12           }));
13         }
14       });
15     }
16   }
17 );

The event name is your personal choice. It’s as customizable as any name. If you want to transfer custom data the class CustomEvent is better than just using Event. This type provides an additional property detail. The receiving component must also access the content of the slot, not the actual definition. The complete example is written in TypeScript. Due to the types it gives a better understanding.

 1 class MenuItem extends HTMLElement {
 2 
 3   constructor() {
 4     super();
 5   }
 6 
 7   connectedCallback() {
 8     this.attachShadow({ mode: 'open' });
 9     if (this.shadowRoot) {
10       this.shadowRoot.innerHTML = `<li>${this.textContent}</li>`;
11       this.shadowRoot.addEventListener('click', (e: Event) => {
12         if ((e.target as HTMLElement).tagName === 'LI') {
13           console.log(e);
14           const customEvent: CustomEventInit = {
15             detail: (e.currentTarget as HTMLElement).textContent
16           };
17           this.dispatchEvent(new CustomEvent('menuclick', customEvent));
18         }
19       });
20     }
21   }
22 }
23 
24 class CustomMenu extends HTMLElement {
25 
26   constructor() {
27     super();
28   }
29 
30   connectedCallback() {
31     this.attachShadow({ mode: 'open' });
32     if (this.shadowRoot) {
33       this.shadowRoot.innerHTML = `
34               <div>
35                 <slot name="title"></div>
36                 <ul>
37                   <slot name="item"></slot>
38                 </ul>
39               </div>`;
40       const slot = this
41             .shadowRoot
42             .querySelector<HTMLSlotElement>('slot[name="item"]');
43       if (slot) {
44         slot.assignedNodes()
45           .forEach((e: Node) => {
46             e.addEventListener('menuclick', (el: Event) =>
47               alert((el as CustomEvent).detail));
48           });
49       }
50     }
51   }
52 }
53 
54 customElements.define('menu-item', MenuItem);
55 customElements.define('custom-menu', CustomMenu);