DEV Community

Cover image for Lets Build Web Components! Part 1: The Standards
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ

Posted on • Updated on

Lets Build Web Components! Part 1: The Standards

Component-based UI is all the rage these days. In fact it's so established that people have even started retconning old-school jQuery widgets as "jQuery Components" ;)

When we say "Component", we're mostly referring to self-contained, reusable bits of UI which, once written, we can insert into our apps wherever we want. Fancy interactive buttons, specially designed pull-quotes, or the perennial favourite card widgets are examples of the types of designs that lend themselves well to components.

Did you know that the web has its own native component module that doesn't require the use of any libraries? True story! You can write, publish, and reuse single-file components that will work in any* good browser and in any framework (if that's your bag). Read on to find out how!


Web Components is an umbrella term that refers to a set of four browser standards that work together to form the web's native component model.

  1. <template> elements let you quickly reuse portions of DOM
  2. Custom Elements connect JS classes to custom HTML tags
  3. Shadow DOM hides your shame from the rest of the page
  4. JavaScript Modules to package and publish components

Each of these standards provides one piece of the puzzle. In this introductory post, we're going to briefly introduce each of them and explain how they help us in practical web development.

<template> Elements

The fundamental idea of components is reusable UI. To create that, we need a way to define a template for our component. If you're familiar with React, then you've probably used JSX before. If you're more an Angular type, you've likely defined templates in JavaScript template literals.

The <template> element lets us define snippets of HTML which aren't added to the document until cloned by JavaScript. The browser only needs to parse that HTML once (e.g. when the document loads), and can then clone it cheaply whenever asked to.

Here's a (really contrived) example of the template element in action:

<template id="dialog-template">
    <button>โš“๏ธ All Ashore!</button>

  Type a <abbr title="message"> ๐Ÿ’Œ</abbr>
  <input id="input"/>

<button id="clone-it"><abbr title="Go!">๐Ÿฆ‘ Ahoy!</abbr></button>

  document.getElementById('clone-it').onclick = () => superAlert(input.value);

  function superAlert(message) {
    // get a reference to the template
    const template = document.getElementById('dialog-template');
    // clone or "stamp" the template's contents
    const clone = template.content.cloneNode(true);

    // Make any changes to the stamped content
    const diag = clone.firstElementChild;

    // <dialog> element polyfill

    diag.firstElementChild.textContent = message;
    diag.lastElementChild.onclick = function closeModal() {

Using <template> elements is easy and performant. I put together a silly little benchmark that builds a simple table three ways: by cloning a template element, by directly using DOM APIs, and by setting innerHTML. Cloning template elements is the fastest, DOM APIs are a little slower, and innerHTML is slowest by far.

Template Elements: 55877 Operations / second. DOM APIs: 51666 Operations / second. Template Literals: 44102 Operations / second

So the <template> element lets us parse HTML once and reuse it as many times as we want. Exactly like what we need for our reusable components!

Read more about the <template> element and it's DOM API at MDN.

Custom Elements

The second standard we're going to take a look at is called custom elements. It does exactly what it says on the box: it lets you define your own custom HTML tags. Now you don't have to settle for just plain old <div> and <span>, but you can mark up your pages with <super-div> and <wicked-span> as well.

Custom Elements work just like built-in elements; add them your document, give them child elements, use regular DOM APIs on them, etc. You can use custom elements everywhere you use regular elements, including in popular web frameworks

All custom element tag names must contain a dash, to differentiate them from built in elements. This also helps to avoid name conflicts when you want to use <bobs-input> and <sallys-input> in the same app. As well, Custom elements can have their own custom attributes, DOM properties, methods and behaviours.

An example of how you might use a custom element:

  <p>Twinkle, twinkle, little <super-span animation="shine">star</super-span>.</p>
  <awesome-button exuberant>Shine it!</awesome-button>

Custom elements are defined as JavaScript classes, and registered on the window.customElements object via its define method, which has two parameters: a string to define the element's name, and a JavaScript class to define its behaviour.

This example takes a boring old <span> and gives it emoji super-powers! Give it a try.

customElements.define('super-span', class SuperSpan extends HTMLElement {
   * `connectedCallback` is a custom-element lifecycle callback
   * which fires whenever the element is added to the document
  connectedCallback() {
    this.addEventListener('click', this.beAwesome.bind(this)) = 'inline-block';
    this.setAttribute('aria-label', this.innerText);
    switch (this.innerText) {
      case 'star': this.innerText = 'โญ๏ธ';

   * You can define your own methods on your elements.
   * @param  {Event} event
   * @return {Animation}
  beAwesome(event) {
    let keyframes = [];
    let options = {duration: 300, iterations: 5, easing: 'ease-in-out'}
    switch (this.getAttribute('animation')) {
      case 'shine': keyframes = [
        {opacity: 1.0, blur: '0px', transform: 'rotate(0deg)'},
        {opacity: 0.7, blur: '2px', transform: 'rotate(360deg)'},
        {opacity: 1.0, blur: '0px', transform: 'rotate(0deg)'},
    return this.animate(keyframes, options)

Custom Elements have built-in features like lifecycle callbacks and observed attributes. We'll cover those in a later post. Spoiler alert: You can read all about custom elements on MDN

Shadow DOM

What stalks the document tree, hiding in the shadows, the dark places where innocent nodes fear to tread?

Dada dada dada dada! Shadow DOM!

I am darkness. I am the night. I am Shadow DOM!

Batman lurking in the shadows

Although "Shadow DOM" might sound exotic, it turns out you've been using it for years. Every time you've used a <video> element with controls, or an <input> element with a datalist, or others like the date picker element, you've been using Shadow DOM.

Shadow DOM is simply an HTML document fragment that is visible to the user while at the same time isolated from the rest of the document. Similarly to how iframes separate one document from another embedded document, shadow roots separate a portion of a document from the main document.

For example, the controls in a video element are actually a separate DOM tree which lives, batman-like, in the shadows of your page. Global styles don't affect the video controls, and the same is true vice-versa.

Screenshot of Firefox developer tools highlighting the use of a shadow root on

An example of Shadow DOM being used on to isolate DOM from the rest of the page

Why is isolating DOM a good thing? When working on web apps of any non-trivial size, CSS rules and selectors can quickly get out of hand. You might write the perfect CSS for a single section of your page, only to have your styles overruled by your teammate further down the cascade. Even worse, your new additions to the app might break existing content without anyone noticing!

Many solutions to this problem have been developed over time, from strict naming conventions to 'CSS-in-JS', but none of them are particularly satisfying. With shadow DOM, we have a comprehensive solution built in to the browser.

Shadow DOM isolates DOM nodes, letting you style your components freely, without worrying that other portions of the app might clobber them. Instead of reaching for arcane class names or stuffing everything into the style attribute, you can style your components in a simple, straightforward way:

<template id="component-template">
    :host {
      display: block;

    /* These styles apply only to button Elements
     * within the shadow root of this component */
    button {
      background: rebeccapurple;
      color: inherit;
      font-size: inherit;
      padding: 10px;
      border-radius: 4px;
      /* CSS Custom Properties can pierce the shadow boundary,
       * allowing users to style specific parts of components */
      border: 1px solid var(--component-border-color, ivory);
      width: 100%;


  <!-- This ID is local to the shadow-root. -->
  <!-- No need to worry that another #button exists. -->
  <button id="button">I'm an awesome button!</button>

  /* These styles affect the entire document, but not any shadow-roots inside of it */
  button {
    background: cornflowerblue;
    color: white;
    padding: 10px;
    border: none;
    margin-top: 20px;

  /* Custom Elements can be styled just like normal elements.
   * These styles will be applied to the element's :host */
  awesome-button {
    width: 280px;
    font-size: inherit;


<button id="button">I'm an OK button!</button>

<section id="display">
  <abbr title="click">๐Ÿ–ฑ</abbr> a <abbr title="button">๐Ÿ”ฒ</abbr>

Shadow DOM is the secret sauce in web components. It's what makes them self-contained. It's what gives us the confidence to drop them into a page without worrying about breaking other parts of the app.

And starting with Firefox 63, it's available natively on all good browsers.

Read more about Shadow DOM on MDN

With these three standards: Template, Custom Elements, and Shadow DOM, we have everything we need to write rich component UIs that run directly in the browser without needing any special tooling or build steps. The fourth standard, JavaScript Modules, enables us to factor complex apps composed of custom elements and publish our components for others to use.

JavaScript Modules

When we use the word module, what we mean is a freestanding piece of software which contains its own scope. In other words, if I define a variable foo in some module, I can only use that variable inside that module. If I want to access foo in some other module, I'll need to explicitly export it first.

Developers have been finding ways to write modular JavaScript for some time now, but it's only been fairly recently (since 2015 in the specs, and for the last year or so in practice) that JavaScript has had its own module system.

import { foo } from './foo.js'

const bar = 'bar'

export const baz = foo(bar)

There's a lot to say about modules, but for our purposes, it's enough that we can use them to write and publish web components.

Here's a simple example to whet your appetite.

// super-span.js

const options = {duration: 300, iterations: 5, easing: 'ease-in-out'}
const keyframes = [
  {opacity: 1.0, blur: '0px', transform: 'rotate(0deg)'},
  {opacity: 0.7, blur: '2px', transform: 'rotate(360deg)'},
  {opacity: 1.0, blur: '0px', transform: 'rotate(0deg)'},

const template = document.createElement('template')
template.innerHTML = `
    span {
      display: inline-block;
      font-weight: var(--super-font-weight, bolder);
  <abbr title="click or mouse over">๐Ÿ–ฑ</abbr>

customElements.define('super-span', class SuperSpan extends HTMLElement {

  $(selector) {
    return this.shadowRoot && this.shadowRoot.querySelector(selector)

  constructor() {
    this.shine = this.shine.bind(this)
    const root = this.attachShadow({mode: 'open'})
    this.addEventListener('click', this.shine)
    this.addEventListener('mouseover', this.shine)

  connectedCallback() {
    const slot = this.$('slot')
    const [node] = slot.assignedNodes()
    this.setAttribute('aria-label', node.textContent)
    node.textContent = 'โญ๏ธ'

  shine(event) {
    this.$('span').animate(keyframes, options)

And then in our app's HTML:

<script type="module" src="./super-span.js"></script>

And this, my friends, is the coin-drop moment when you realize how awesome web components can be.

Now you can easily import pre-made custom elements with awesome behaviour and semantics right into your documents, without any build step.

<!DOCTYPE html>
<html lang="en" dir="ltr">
    <meta charset="utf-8">
    <title>Be Excellent to Each Other</title>
    <script type="module" src="//"></script>
    <script type="module" src="//"></script>
    <script type="module" src="//"></script>
    <link rel="stylesheet" href="style.css">
      <h1>Cross-platform, Framework-Agnostic, Reusable Components</h1>

      <granite-alert id="alert" level="warning" hide>
        <lazy-image role="presentation"

      <mwc-button id="button" raised>๐Ÿš€ Launch</mwc-button>

        const alert = document.getElementById('alert')
        const button = document.getElementById('button')
        const message = document.getElementById('message')
        button.onclick = () => {
          alert.hide = !alert.hide;
          button.textContent = alert.hide ? '๐Ÿš€ Launch' : 'โ˜ ๏ธ Close'


Web components standards let us factor self-contained, reusable UI that runs directly in the browser without cumbersome build steps. These components can then be used anywhere you use regular elements: in plain HTML, or within your app's framework-driven templates.

In our next post, God-willing, we'll learn how the webcomponentsjs polyfills let us design components and compose apps even for browsers that don't natively support them.

๐Ÿ˜€ Thanks for reading! ๐Ÿ˜

Check out the next article in the series

Would you like a one-on-one mentoring session on any of the topics covered here? Contact me on Codementor


Discussion (22)

jochemstoel profile image
Jochem Stoel

๐Ÿ˜€ Thanks for reading! ๐Ÿ˜

Thanks for writing. Interesting read and very well written. Looking forward to read part two.

I notice that you too use customElements.define and not document.registerElement. I have been wondering if registerElement is (to be) deprecated but never found a satisfying unopioniated answer.
Do you have any insight?

bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author

Exactly right! document.registerElement is deprecated and shouldn't be used.

jochemstoel profile image
Jochem Stoel

@bennypowers I would like to show you document.defineElement/nativeEleme..., a polyfill for custom elements that does not require a hyphen (-) in the HTML tag. It has been a while now since I created that repository but today I added the nativeElements.define() method because you confirmed that registerElement is deprecated in 2018.

Obviously I am aware that this is generally a bad idea to be doing but perhaps you appreciate it nonetheless.

Thread Thread
bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author
Bad ideas completely overwrite the element and break things make iframes or script tags stop working


lasalefamine profile image
Alessio Occhipinti • Edited on

One of the best article on Web Components both for content and clarity. Really great work @bennypowers !

And looking forward for the 2nd part, of course ๐Ÿ”ฅ

kawaiidora profile image

Nice article! Using template.innerHTML are quite hacky and cannot make use of IDE or Editor's features. Is there any way (e.g. load html file) to replace template.innerHTML method in your super-span.js after HTML-import are deprecated?

bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author

I think you'd like to check out lit-element. I have a whole article on it in part 5 of this series.

gabuardi profile image
Josuรฉ Gabuardi • Edited on

totally awesome.. man, I think that this serie of articles are GOLD.

I have researching for web component and web component libraries, I first read the 3 first articles then I start do research in other sites.. after a time... the researching brought me here again. What I mean is that your articles right now are a high quality resource for web components info since what the people usually know about it is almost anything so is difficult to found something like this.

Thanks very much to share!

bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author

Thanks for the kind words ๐Ÿ˜

david_j_eddy profile image
David J Eddy

This article has restored my faith in the Javascript ecosystem. Thank you Benny.

bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author

That's what we came here for :)

Glad you enjoyed it.

satyakresna profile image
Satya Kresna

Excellent example you bring about web components. Awesome!

bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author

Thank you, Satya!
Please enjoy the other posts in the series.

teej profile image
TJ Fogarty

Great post, and a great resource in general. I'll be referring to this a lot when I'm trying to learn more. Really looking forward to the next one :)

bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author

Thanks, TJ :D

crapkit profile image
Patrick Nemenz • Edited on

Thanks, Benny!

This post really opened my eyes on how far the standard has come since the old days of Polymer. Much like your write-up, the syntax is finally clear and concise.

adityasridhar profile image
Aditya Sridhar

Really great article. Thanks for taking the time to write this :)

paramsinghvc profile image
Parminder Singh

Here's an example of implementing config driven UI elements using custom components.

stefant123 profile image

One of the best posts I've read. Very well explained. It will be a nice future reference. Can't wait for the next one.

bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author

Thank you! ๐Ÿ˜

phnx311 profile image
Eric Chi

Hi Benny I've never seen the element method .content from const

clone = template.content.cloneNode(true);

Is this new or just something thats always been available?

bennypowers profile image
Benny Powers ๐Ÿ‡ฎ๐Ÿ‡ฑ๐Ÿ‡จ๐Ÿ‡ฆ Author

Hey Eric thanks for dropping by ๐Ÿป

content is a read-only property on HTMLTemplateElement that's not provided on other elements. It's purpose is to give you a handle on the template's contents as a DocumentFragment, so that you can clone it.