Forem: Chris Haynes

How to detect clicks outside of a Web Component

Chris Haynes — Sat, 10 Apr 2021 00:00:00 +0000

When using Web Components it's often necessary to be able to distinguish between clicks inside the component from those outside of it.

For example you may want to show some content when a button is clicked, and then hide it when the user clicks outside the component but not when the user clicks inside the component:

The problem

What may seem a simple problem becomes more complicated when you consider how events are treated differently depending on whether an element is in the Shadow DOM or in the Light DOM.

Take the following component definition used in the above example:

<my-component>
  #shadow-root
    <button>Open</button>
    <button>Button A</button>
    <slot><slot>

  <button>Button B</button>
</my-component>

The desired behaviour is:

close when you click outside the component
do not close when the component itself is clicked
do not close when an element in the Shadow DOM is clicked (Button A)
do not close when an element in the Light DOM is clicked (Button B)

A first attempt may be to add an event listener defined inside your component like this:

document.addEventListener('click', (event) => {
  if (event.target !== this) {
    this.close();
  }
});

✅ For a click outside the component event.target !== this so the component will close.
✅ For a click on the component itself event.target === this so the component will not close.
✅ For a click on Button A inside the Shadow DOM,event.target === this so the component will not close.
❌ For a click on Button B inside the Light DOM event.target !== this so the component will close.

But why is event.target === this for elements inside the Shadow DOM, but not for elements inside the Light DOM?

Event retargeting

For elements inside the Shadow DOM events are automatically retargeted to the parent component. This means that event.target is set to the parent component for any event originating from inside the Shadow DOM.

But for elements in the Light DOM, which are only projected to the inside of a component and are not physically moved there, the event.target remains set to the element itself.

So how do you find out if an element in a component's Light DOM was clicked?

The solution

The event.composedPath() method shows you each element the event passed through from the originating element right up to the Window object at the top of the DOM tree. This works on the projected DOM tree so that the elements are included in the order that they appear when rendered rather than their physical position in the DOM:

document.addEventListener('click', (event) => {
  console.log(event.composedPath());
  /*
    this will log an array containing the following
    when a button in the Shadow DOM is clicked:

    0: button.A
    1: div#container
    2: document-fragment
    3: my-component <--
    4: body
    5: html
    6: document
    7: Window

    and the following when a button in the Light DOM is clicked:

    0: button.B
    1: slot
    2: div#container
    3: document-fragment
    4: my-component <--
    5: body
    6: html
    7: document
    8: Window
  */
});

In both cases you can see that my-component appears in the composed path. Using this fact you can update the event listener to the following:

document.addEventListener('click', (event) => {
  if (!event.composedPath().includes(this)) {
    this.close();
  }
});

✅ For a click outside the component composedPath() will not include the component (this) so the component will close.
✅ For a click on the component itself composedPath() will include this so the component will not close.
✅ For a click on Button A inside the Shadow DOM,composedPath() will include this so the component will not close.
✅ For a click on Button B inside the Light DOM composedPath() will include this so the component will not close.

🎆 Bingo, composedPath() gives you all the information you need to see where the event originated!

You can view a full code example of the above component here.

Subscribe to my mailing list to be notified of new posts about Web Components and building performant websites

How to share styles in the Shadow DOM

Chris Haynes — Tue, 23 Mar 2021 00:00:00 +0000

The Shadow DOM is great for insulating your Web Components from global style rules, but what do you do if you want to share common styling between components? One approach is to duplicate style rules across components but that can be inefficient and a maintenance headache - surely there's another way?

The problem

Let's take a simplified Card component containing a button, and place it on a page also containing a button:

class MyCard extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    // these should be sanitized!
    const title = this.getAttribute('my-title');
    const content = this.getAttribute('my-content');

    this.shadowRoot.innerHTML = `
      <style>
        :host {
          display: flex;
          flex-direction: column;
          border: 1px solid #ddd;
          border-radius: 0.2rem;
        }

        #title {
          display: flex;
          align-items: center;
          justify-content: space-between;
          padding: 1rem;
          font-size: 2rem;
          border-bottom: 1px solid #ddd;
        }

        #content {
          padding: 1rem;
        }
      </style>

      <div id="title">
        ${title}
        <button>I am inside a component, click me!</button>
      </div>

      <div id="content">${content}</div>
      `;
  }
}

customElements.define('my-card', MyCard);

<p>
  <button>I'm not in a component</button>
</p>

<my-card my-title="Hello" my-content="Welcome to the jungle!"></my-card>

which gives us:

The challenge then is how to style the button so that it looks the same both inside and outside of your component. Let's use the following CSS to style your button:

button {
  border: 0;
  padding: 0.5rem;
  border-radius: 0.2rem;
  background-color: steelblue;
  color: white;
}

Where do you put these styles so they apply to the outer page and inside your component?

The wrong way

The wrong way is to add those styles to your page's stylesheet:

<link rel="stylesheet" href="/button.css" />
<!-- button.css contains the buttons styles above -->

AND in the style block inside your component's Shadow DOM:

<style>
  button {
    /* button styles here */
  }

  /* your component specific styles go here*/
</style>

As you may have spotted, this has several limitations:

Duplication - if you want to change your button styling, you have to update it in your stylesheet and in every component that contains a button.
Wasted bytes - the browser has to download the same CSS for the outer page and for every component.
Not dynamic - if you want to update the styling dynamically then you are out of luck.

A better way

Luckily <link> tags are valid inside the Shadow DOM as well as in your outer page, so you can use the link from the outer page:

<link rel="stylesheet" href="/button.css" />
<!-- button.css contains the buttons styles above -->

and re-use it in your component's Shadow DOM:

...
this.shadowRoot.innerHTML = `
  <link rel="stylesheet" href="/button.css" />
  <style>
    /* your component specific styles go here */
  </style>
  ...
`;
...

In this way you:

Avoid duplication - you only have to write your styles once, inside the stylesheet.
No wasted bytes - as long as the stylesheet is sent with sensible caching headers, only the first time the stylesheet is encountered will it need to be downloaded. Subsequent requests for the stylesheet will come straight from the cache.

Note that if you only include the <link>in your components, and not in the outer page, you risk the dreaded flash of unstyled content (FOUC). This is because <link> tags in the ShadowDOM are not render blocking - in other words the browser will display the content of your Shadow DOM before the styles have been downloaded and parsed. By adding the <link> to your outer page (where it is render blocking) this will force the browser to download the styles before it attempts to display any content. Then when the browser encounters the <link> again inside your component it will already have been cached and ready to apply immediately.

Dynamic styles

But one issue remains with this better approach - if you want to dynamically update the styling of your button there still isn't once place where you can change the style and have it update the style of all your buttons.

Both the outer page and each of your components are using a copy of the same stylesheet, not a single instance, so changing a style in one instance of the stylesheet won't be replicated in all the other instances.

Now this may well not be an issue if you don't need this functionality, in which case crack open the champagne and put your dancing shoes on - you're all set. But if you do, you have a 2 further options:

CSS Custom Properties (CSS variables) - CSS custom properties defined on the outer document are available automatically inside your Shadow DOM. So you could define some custom properties in your document, and refer to them in your button's styles. Updating the properties in JavaScript would then apply them to all your button instances. This works but does mean you have to add lots of custom properties if you want to control all aspects of styling, and you still can't add new styles this way.
Constructable Stylesheets - Constructable Stylesheets are a proposal to address the exact issue of reusing the same stylesheet across documents and Shadow roots, and providing a simpler way to add and update styles in a stylesheet. Unfortunately they have only been implemented in Chrome (with only tepid support from other browsers) so they may not be a viable option, although a polyfill is available. Find out more in the Google developer docs.

Wrap-up

Using the same <link> tag both in your outer document and inside your component's Shadow DOM is currently the best way to share styles across your components without code duplication, while CSS custom properties provide a well supported, albeit somewhat limited, way of dynamically updating shared styles. Constructable Stylesheets promise a better approach to re-using and dynamically updating styles but with limited support at this time.

Subscribe to my mailing list to be notified of new posts about Web Components and building performant websites

When are the constructor and connectedCallback methods called when creating a Custom Element?

Chris Haynes — Mon, 15 Mar 2021 00:00:00 +0000

The constructor and connectedCallback lifecycle methods of Custom Elements are called when your element is created and attached to the DOM respectively, but there are a few subtleties to keep in mind depending on how and when you define, create, insert and declare your element.

So how are Custom Elements defined, created, inserted and declared? And at which stage do the lifecycle methods get called?

Define

A custom element is defined when customElements.define is called:

class MyElement extends HTMLElement {
    constructor() {
        super();

        console.log('constructed');
    }

    connectedCallback() {
        console.log('connected');
    }
}

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

Defining an element doesn't trigger either the constructor or the connectedCallback methods since it does not create an instance of an element

An element can only be defined once.

Create

An element can be created in JavaScript in two ways:

// can happen before definition
const myElement = document.createElement('my-element');

// can only happen if already defined
const myElement = new MyElement();

Creation triggers the constructor, if the element has already been defined.

The constructor is only ever called once per element instance.

Insert

An element is inserted into the DOM imperatively with JS:

document.body.append(myElement);

Insertion triggers the connectedCallback method, if the element has already been defined.

connectedCallback is called each time the element is inserted into the DOM, with the disconnectedCallback method called each time it is removed from the DOM.

Declare

An element is declared when parsed as HTML:

<my-element></my-element>

document.body.innerHTML = '<my-element></my-element>';

Declaration triggers the constructor and connectedCallback methods, if the element has already been defined.

Upgrade

In all the above cases the lifecycle methods are only called if the element has already been defined. An element is upgraded when it already exists before definition - at the point of definition the constructor is then called automatically. If the element was already attached to the DOM at this point connectedCallback will also be called.

Examples

The examples below cover the different orders of the above stages to illustrate when the lifecycle methods are called.

Define then Declare

<html>
    <head>
        <script>
            class MyElement extends HTMLElement {
                constructor() {
                    super();

                    console.log('constructed');
                }

                connectedCallback() {
                    console.log('connected');
                }
            }

            customElements.define('my-element', MyElement);
        </script>
    </head>
    <body>
        <my-element></my-element>
        <!-- `constructor` then `connectedCallback` are called here when the element has been parsed -->
    </body>
</html>

Declare then Define

<html>
    <head>
    </head>
    <body>
        <my-element></my-element>

        <script>
            class MyElement extends HTMLElement {
                constructor() {
                    super();

                    console.log('constructed');
                }

                connectedCallback() {
                    console.log('connected');
                }
            }

            // UPGRADE
            customElements.define('my-element', MyElement);
            /**
            `constructor` then `connectedCallback` are called here when the element has been defined -->
            **/
        </script>
    </body>
</html>

Define then Create then Insert

<html>
    <head>
    </head>
    <body>
        <script>
            class MyElement extends HTMLElement {
                constructor() {
                    super();

                    console.log('constructed');
                }

                connectedCallback() {
                    console.log('connected');
                }
            }

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

            const myElement = document.createElement('my-element');
            /**
            `constructor` called here when element is created
            **/

            document.body.appendChild(myElement);
            /**
            `connectedCallback` called here when element is inserted
            **/
        </script>
    </body>
</html>

Create then Insert then Define

<html>
    <head>
    </head>
    <body>
        <script>
            const myElement = document.createElement('my-element');

            document.body.appendChild(myElement);

            class MyElement extends HTMLElement {
                constructor() {
                    super();

                    console.log('constructed');
                }

                connectedCallback() {
                    console.log('connected');
                }
            }

            // UPGRADE
            customElements.define('my-element', MyElement);
            /**
            `constructor` then `connectedCallback` are called here when the element has been defined -->
            **/
        </script>
    </body>
</html>

Create then Define then Insert

<html>
    <head>
    </head>
    <body>
        <script>
            const myElement = document.createElement('my-element');

            class MyElement extends HTMLElement {
                constructor() {
                    super();

                    console.log('constructed');
                }

                connectedCallback() {
                    console.log('connected');
                }
            }

            // UPGRADE
            customElements.define('my-element', MyElement);
            /**
            `constructor` called here when the element has been defined
            **/

            document.body.appendChild(myElement);
            /**
            `connectedCallback` called here when the element has been defined -->
            **/
        </script>
    </body>
</html>

Why does any of this matter?

Knowing when, how and why the constructor and connectedCallback methods are called is important when initialising your Custom Elements. Generally:

the constructor is best suited to setting up initial state and events that don't need to be removed or cleaned up when the element is destroyed (as there is no deconstructor method.)
the constructor is only ever called once per element so initialisation that needs to happen each time the element is attached to the DOM should be deferred to connectedCallback.
the connectedCallback method is best suited to most other initialisation tasks. Any clean up can then happen in disconnectedCallback.
attributes and child elements should not be accessed or modified in the constructor since, depending on how the element is created, they may not exist e.g. document.createElement('my-element'); - this will trigger the constructor but the element has had no chance yet to set attributes or children.
if you need to access / modify attributes or children on initialisation this must therefore happen in connectedCallback. In this case you will often need to guard against such initialisation happening multiple times as the element is removed and re-attached to the DOM.

Subscribe to my mailing list to be notified of new posts about Web Components and building performant websites

What's the difference between Web Component attributes and properties?

Chris Haynes — Thu, 30 Apr 2020 00:00:00 +0000

A common confusion with Web Components is the difference between attributes and properties and the relation between them.

Attributes

In common with the built in elements, attributes are strings that are set declaratively on the tag itself:

<my-wc myattribute="Ada"></my-wc>

or set imperatively using setAttribute:

const myWC = document.querySelector('my-wc');
myWC.setAttribute('myattribute', 'Ada');

Properties

Properties on the other hand are values of any type that can be set imperatively directly on the element instance:

const myWC = document.querySelector('my-wc');
myWC.myattribute = 'Lovelace';
// the value could be any type - string, number, boolean, object, function etc.

Relationship between attributes and properties

By default there is none - they can co-exist with the same name and changing one has no effect on the other:

console.log(myWC.getAttribute('myattribute')); // 'Ada'
console.log(myWC.myattribute)); // 'Lovelace'

Of course that can be confusing in contrast with most of the built in elements where there is a relationship between attributes and properties with the same name. There are generally two scenarios:

The declared attribute initialises a property with the same name, but subsequent changes to the attribute have no effect on the property, and likewise changes to the property are not reflected in an updated attribute value. This is how the value attribute/property pairing works on the standard input element.
The attribute and property are always kept in sync - any changes to the property are reflected in the attribute and vice-versa. An example of this is the id attribute/property pairing of all elements.

So how do we reproduce these two scenarios on our new element which has no attribute/property relationship by default? To do this we need to manually set up the relationship ourselves.

Using the attribute as a property initialiser

This is the simplest case - all we need to do is check the value of the attribute when the element is added to the DOM - the property will then take the value of the attribute currently defined (either in the markup, or set using setAttribute on a programmatically defined instance):

class MyWC extends HTMLElement {
  constructor() {
    super();

    this.myattribute = 'Kevin'; // our default property value
  }

  connectedCallback() {
    const attributeValue = this.getAttribute('myattribute');
    // Note non-existant attributes will return null
    if (attributeValue !== null) {
      this.myattribute = attributeValue;
    }
  }
}

Keeping the attribute and property in sync

This scenario takes more set up - we need to monitor the attribute and property for changes so we can mirror the values to each other:

class MyWC extends HTMLElement {
  // ensure `attributeChangedCallback` is called when our attribute changes:
  static get observedAttributes() {
    return ['myattribute'];
  }

  constructor() {
    super();

    // We need to store our property value in a new object - without this
    // we can't use the getter/setters we need below

    this._props = {
      myattribute: 'Kevin',
    };
  }

  connectedCallback() {
    const attributeValue = this.getAttribute('myattribute');
    // Note non-existant attributes will return null
    if (attributeValue !== null) {
      this._props.myattribute = attributeValue;
    }
  }

  get myattribute() {
    // return our property value
    return this._props.myattribute;
  }

  set myattribute(value) {
    // set our property value
    this._props.myattribute = value;

    // update our attribute of the same name
    this.setAttribute('myattribute', value);
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'myattribute') {
      // when our attribute changes update our property value
      // we can't set the property using the setter (i.e. this.myattribute = value)
      // as this would cause an infinite loop
      this._props.myattribute = newValue;
    }
  }
}

Keep in mind the above implementations are for string based properties - you'll need a few extra steps for boolean or numeric properties. Non-primitive types (functions, objects, etc.) are not generally reflected to or initialised from attributes.

There is also a convention to camelCase (e.g. myAttribute) property names and kebab-case attribute names (e.g. my-attribute). This conversion would also require some further steps not detailed above.

Which scenario should I choose?

Initialising properties from attributes is the simplest choice, and the one I would recommend unless you have a reason not to. However there are times when it's useful to keep the attribute value in sync with the property value - a common case is being able to use CSS attribute selectors to match elements depending on their current state - in which case the second method is required.

Showing different fallback content with Web Components

Chris Haynes — Thu, 23 Apr 2020 00:00:00 +0000

With web components there's often a need to render fallback content - both to show content in browsers that don't have support for web components (or with JavaScript disabled/broken) and to show content to the user while the web component is being loaded/initialised. The trouble is that we probably want to display different fallback content in these two scenarios - perhaps alternative static content in the first case and a loading indicator in the latter.

Fallback content is provided by supplying HTML between our custom element tags, but how do we have 2 different version of fallback content?

To achieve this we first build our component as normal:

class WCExample extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    this.render();
  }

  render() {
    this.shadowRoot.innerHTML = `
      <style>
      :host {
        display: block;
        padding: 1rem;
        color: steelblue;
        border: 1px solid steelblue;
      }
      </style>

      <p>Loaded and ready to go!</p>
    `;
  }
}

customElements.define('wc-example', WCExample);

Next we provide our two versions of fallback content inside out new element, providing different classes to each:

<wc-example>
  <p class="no-wc">
    A static version of the content
  </p>
  <p class="has-wc">
    Please wait...
  </p>
</wc-example>

If we were to load this HTML in the browser we'd see both versions of the fallback content until the component code is loaded. However if we apply a class to the body indicating no web component support, .no-wc, and immediately remove it just after the body tag if web components are supported (before the component code is loaded or the component tag is rendered):

if (window.customElements) {
  document.querySelector('body').classList.remove('no-wc');
}

The body will then only have the .no-wc class if JavaScript has run and Web Components are supported. We can then control which version is displayed with a couple of global CSS rules:

body.no-wc .has-wc {
  display: none;
}

body:not(.no-wc) .no-wc {
  display: none;
}

See this in action here (with an artifical delay applied to the loading of the Web Component code). Be sure to test with and without JavaScipt enabled to see the difference.

Lazy loading Web Components with Intersection Observer

Chris Haynes — Fri, 20 Mar 2020 00:00:00 +0000

One of the many benefits of adopting Web Components (WC) as your component model of choice is that you can make direct use native web platform features with no modifications, wrappers or build scripts. One such example is using the Intersection Observer API and dynamic imports to load WC only when they're needed on the page. Using this pattern defers the loading of the component source on modern browsers until the tag is visible on the page, so:

if a user visits on a browser that can't or won't run JavaScript, they won't download the JS that they'll never use
if a user visits on a browser that doesn't support WC, they won't download the JS that they'll never use.
if a user visits on a browser that does support WC but doesn't visit a page containing the WC, they won't download the JS that they'll never use
if a user visits on a browser that does support WC and does visit a page containing the WC, but doesn't scroll to the part of the page that contains the WC, they won't download the JS that they'll never use
if a user visits on a browser that does support WC and does visit a page containing the WC, and does scroll to the part of the page that contains the WC, they'll download the JS that they require on demand.

In this way we can progressively enhance the user experience not only based on browser features, but also only when a component is actually required. All this can be achieved with just a few lines of code:

// keep a record of the components we've loaded in this way
const imported = {};
// Set up our observer:
let observer = new IntersectionObserver((entries, observerRef) => {
  // The callback is run when the visibility of one or more of the elements
  // being observed has changed. It's also called on page load.
  entries.forEach(async entry => {
    //`isIntersecting` will be `true` if any part of the element is currently visible
    if (entry.isIntersecting) {
      // We are assuming here that your Web Component is located in a file
      // named after it's tag name
      const name = entry.target.nodeName.toLowerCase();

      // Once we've observed this element come into view, we can safely remove
      // the observer since we won't need to import the WC code again
      observerRef.unobserve(entry.target);

      if (!imported[name]) {
        // Keep a note of which WCs have been loaded so if we have multiple
        // instances we don't import twice
        imported[name] = true;

        // Let's load the WC code
        import(`./${name}.js`);
      }
    }
  });
});

// Observe all components with the desired class
const els = document.querySelectorAll('.dynamic-element');
els.forEach(el => {
  observer.observe(el);
});

And that's it. The observer callback is run when the visibility of one or more of the elements being observed has changed. There are 3 scenarios:

The element has just come into view
The amount of the element that's visible has changed
The element has just gone out of view

Here we're only interested in the first case so isIntersecting is all we need - when that's true we know the component has just come into view and we can import the required code. We can also detach the observer so it's not called again when the element (or others of the same type) come into view again. Note that the observer is always run on page load so that if there's a component on screen when the page is loaded it's immediately imported.

I've added an example on my site's version of this post. By the time you've scrolled to the end of the page the browser will have dynamically loaded the <lamplight-lazy></lamplight-lazy> component (check in devtools to see the lamplight-lazy.js file loaded when you scroll to this point.)

Thanks for reading, and let me know if you have any other tips for progressive enhancement with Web Components!

Web Components aren't a framework replacement - they're better than that

Chris Haynes — Sat, 18 Jan 2020 00:00:00 +0000

With the release of the Chromium based Edge browser, and Web Components now being available in all major browsers, it's worth taking a moment to discuss what Web Components are, what they are not, and how they relate to the established UI frameworks such as React, Vue, and Angular.

Identity problem

Web Components mean different things to different people. Officially they a group of 3 language features:

Custom Elements - a set of APIs to create new HTML elements
Shadow DOM - the ability to encapsulate both the DOM and styling inside an element
HTML Templates - a way of creating DOM independent of the current document

While this grouping makes sense in that all three can be used while creating Web Components, only Custom Elements themselves are required to create one.

Shadow DOM is a great addition to the web, but you can create Web Components without it (indeed you can even use Shadow DOM outside of Custom Elements, although I'm not sure why you'd want to).

Similarly HTML Templates can be used with Web Components but are by no means necessary, and have a wider use outside of Web Components. For these reasons I prefer to think of Web Components as Custom Elements only, and refer to the Shadow DOM and/or HTML Templates explicitly when used.

For the remainder of this post the term Web Components (WC) will refer to Custom Elements.

Building blocks

Let's consider what Web Components are trying to achieve. As part of the extensible web their aim is to provide a basic building block for the web on top of which extra functionality can be added by developers as and when needed. The most fundamental building block of any web site or application are the HTML elements themselves. Built in elements encapsulate their functionality and styling independent of other elements on the page.

Built-in HTML elements

Think of the <video> element - you provide it a source video and it:

knows how to play that video
exposes methods for the developer to control the video
styles it's controls independently of any outside styling
can be manipulated with the standard Javascript DOM API
manages its own lifecycle events such as when it's added or removed from the DOM
integrates seamlessly with DOM based frameworks such as Vue, Angular and many others.

WC provide developers with the ability to create their own HTML elements that behave in exactly the same way as native elements, and can be manipulated with the same native DOM APIs in the browser. As such you can:

Use a WC in a site developed 10 years ago with jQuery.
Re-use a WC internally in a variety of frameworks.
Use a WC developed today in 5 years time with the latest framework.
Use a WC in a simple HTML page with no framework or library.

What's in the box

In common with the frameworks, WC provide:

Component model - a way of encapsulating the functional behaviour of the component
Component lifecycle - methods that can be used to control the behaviour of the component when it's added, removed and updated.

In addition WC uniquely provide:

Style and content encapsulation - through the (optional) use of Shadow DOM the internals of the WC can be styled independently of the containing document. CSS rules are scoped to the element so the element will not inherit unwanted styling from the outside, and ids and classes and any other attributes are scoped to the component.
Interoperability - because they are true HTML elements they they can be used anywhere HTML is expected and are entirely interoperable with past, current and future libraries that deal with HTML elements directly. See Custom Elements Everywhere for full list of interoperable frameworks.
Native implementation - WC are provided built-in to the browser, so there are no 3rd party sources to load, parse, update, or maintain, and no build steps to incorporate. This makes them performant by default.

The missing parts

What WC don't provide, but frameworks do, is any model for:

Managing component state
Reactivity - updating of the component when that state changes
Declarative templating for non-string properties
Server side rendering (SSR) - enabling the component to be fully rendered on the server as sent as a string to the browser so that it can be displayed (although not fully functional) without JavaScript.

The first two of these features are seen as key to writing modern day web apps, and rightly so - handling state and updating elements manually can quickly become cumbersome as the complexity of the app increases.

Declarative templating is a harder comparison to make - while string properties (or more correctly attributes) can be set declaratively, e.g.:

<x-component description="Product"></x-component>

non-string properties (Number, Object, Function etc.) must be set in JavaScript. This is due to the nature of HTML itself - being a markup language there is no way to define non-string properties.

Server side rendering is also more complicated. WC can be rendered on the server since they are just written as HTML elements, but WC making use of the Shadow DOM cannot be without making use of a server side DOM implementation. Even then workarounds must be found to apply styling since the Shadow DOM style is only applied once the component has been instantiated in JavaScript. A declarative Shadow DOM would solve this issue, but that seems some way off at this point, if at all. However with search engines now able to crawl Shadow DOM, and a potential performance cost (sending the component twice, once as an SSR string and again in the component definition) the necessity of SSR may be less important.

The conclusion often made from this is that WC are only suited to being leaf nodes - small self contained elements that are included inside larger more complex apps - and are not suited to being used for building the apps themselves.

A third way

So WC alone are not a replacement for a framework - but they were never intended to be. By their very nature they provide a native, interoperable base on top of which developers can add further functionality if required. In the simplest cases they can be used as-is to build small, performant, re-usable components, but there's nothing to stop component authors adding state management, reactiveness, declaritive templating and more when the need arises. Indeed there are already several well established libraries that enable this functionality to be applied to WC such as lit-html and lit-element.

Indeed having the flexibility to choose when and how these features are integrated in to your component can be seen as an advantage too. They become an implementation detail that can be changed as and when necessary, and because their interface remains the standard HTML element no change is needed in the way they are used whatever the internal details.

Summary

Feature	Web Components	Frameworks
Component model	✓	✓
Component lifecycle	✓	✓
Style encapsulation	✓	✗
Native implementation	✓	✗
Interoperability	✓	✗
Server side rendering	✓ (without Shadow DOM)	✓
Declarative templating	✗	✓
State management	✗	✓
Reactive updates	✗	✓

So it's clear that when deciding to use Web Components, it's not a direct choice between them and a framework.

Existing frameworks provide an all in one solution to building web UIs, but they do so at the expense of locking component authors into their particular implementations and eco-systems. This results in components that are not interoperable or re-usable outside of the chosen framework.

On the other hand native Web Components are fully interoperable and re-usable both inside and outside of existing frameworks and anywhere HTML is used, whilst not providing everything that might be needed to write a complex web app. These 'missing parts' however can be provided quite easily with existing libraries as and when needed, and as Web Components become more popular the range of options to add this functionality will only increase.

How to server side render Web Components

Chris Haynes — Sat, 20 Jul 2019 00:00:00 +0000

Almost all modern framworks provide a way to server side render (SSR) a web site by running the framework code on a JavaScipt server side framework, such as express, to produce an intial string of HTML that can be sent to the browser. The same component code that runs in the browser is also run on the server.

With Web Components there are several limitations when it comes to SSR:

it’s not possible to run the same code on the server since Web Components rely on browser specific DOM APIs that are not available unless you fire up a headless browser or an alternative DOM implementation. Both of these solutions bring a non-trivial overhead that is hard to justify.
Shadow DOM cannot (currently) be represented declaratively so you cannot send it over in your initial string of HTML. Instead you’ll need to implement some other style encapsulation solution (much like the frameworks do.)

So Web Components are certainly at a disadvantage here compared to framework components, but they still offer two main advantages :

less code that runs faster as they use built in platform APIs
future proof as they can be used anywhere , including within current and future frameworks, without modification or risk of obsolesence.

So if these advantages are enough for you to choose Web Components over framework components, how can you SSR Web Components? Well since Web Components without the Shadow DOM are just standard HTML , it’s straightforward.

We’ll use a simple Twitter share button as an example. To see the final result have a look at the demo (or browse the code) and try with and without JavaScript enabled.

On the client

Note: This is a simplified implementation that uses the initial attributes to render the component, with no reactivity to updated attributes or properties - but there is no reason why this could not be added at a later stage in the browser specific part of the code, using vanilla JavaScript or a 3rd party library (for example lit-html and/or lit-element). If you do go down this route also checkout lit-html-server which let’s you use the lit-html syntax on the server.

Our initial, browser based, web component may look something like this:

twitter-share.js

class TwitterShare extends HTMLElement {
  connectedCallback() {
    // set up the props based on the inital attribute values
    this.props = [...this.attributes].reduce((all, attr) => {
      return {
        ...all,
        [attr.nodeName]: attr.nodeValue
      };
    }, {});

    this.render();
  }

  render() {
    // set the innerHTML manually - ShadowDOM can't be used
    this.innerHTML = this.template();

    // add an event listener to the link inside the component
    const a = this.querySelector('a');
    a.addEventListener('click', this.open);
  }

  template() {
    // create the HTML needed for the component
    const { text, url, hashtags, via, related } = this.props;

    const query = [
      text && `text=${encodeURIComponent(text)}`,
      url && `url=${encodeURIComponent(url)}`,
      hashtags && `hashtags=${hashtags}`,
      via && `via=${encodeURIComponent(via)}`,
      related && `related=${encodeURIComponent(related)}`
    ]
      .filter(Boolean)
      .join('&');

    const href = `https://twitter.com/intent/tweet?${query}`;

    return `
      <a target="_blank" noreferrer href="${href}">
        Tweet this
      </a>
    `;
  }

  open(event) {
    // open the twitter share url in a popup window when the link is clicked
    event.preventDefault();

    const a = event.target;
    const w = 600;
    const h = 400;
    const x = (screen.width - w) / 2;
    const y = (screen.height - h) / 2;
    const features = `width=${w},height=${h},left=${x},top=${y}`;

    window.open(a.getAttribute('href'), '_blank', features);
  }
}

customElements.define('twitter-share', TwitterShare);

However, to render this on the server you can’t use HTMLElement, customElements or addEventListener for example as those APIs don’t exist on the server , so you’ll need to extract the template method into a standalone function that can be used:

twitter-share-template.mjs

// .mjs is used here so javascript modules can be used on the server
export default props => {
  // the same logic as above, in a self contained function
  const { text, url, hashtags, via, related } = props;

  const query = [
    text && `text=${encodeURIComponent(text)}`,
    url && `url=${encodeURIComponent(url)}`,
    hashtags && `hashtags=${hashtags}`,
    via && `via=${encodeURIComponent(via)}`,
    related && `related=${encodeURIComponent(related)}`
  ]
    .filter(Boolean)
    .join('&');

  const href = `https://twitter.com/intent/tweet?${query}`;

  return `
    <a target="_blank" noreferrer href="${href}">
      Tweet this
    </a>
  `;
};

and update our browser based component definition to import and use that function:

twitter-share.js

import template from './twitter-share-template.mjs';

class TwitterShare extends HTMLElement {
  //...as before

  render() {
    this.innerHTML = template(this.props);

    // ...as before
  }

  // template() -> removed

  // ...as before
}

customElements.define('twitter-share', TwitterShare);

On the server

On the server, while constructing the page response you need to use the HTML tag for our component with the necessary attributes that will be parsed by the browser, and for the SSR content of the component use the same template function as above:

server.mjs

import template from './public/js/twitter-share-template.mjs';

// ... the server side route

const props = {
  text: 'A Twitter share button with progressive enhancement',
  url: 'https://grave-mirror.glitch.me',
  via: 'lamplightdev'
};

// be sure to sanatize the props if including directly in HTML

response.write(`
  <twitter-share text="${props.text}" url="${props.url}" via="${props.via}">
    ${template(props)}
  </twitter-share>
`);

// ...

To see the component in action have a look at the demo and browse the code. Be sure to try the page with and without JavaScript enabled.

In summary, you can SSR web components without any server side DOM implementation, but only without the Shadow DOM.

If you have any feedback or questions I’d love to hear them @lamplightdev.

Subscribe to the mailing list to be notified of new posts about Web Components and building performant websites

Why is my Web Component inheriting styles?

Chris Haynes — Tue, 26 Mar 2019 00:00:00 +0000

One of the great features of the Shadow DOM in Web Components is that styles are encapsulated to the component - you can style your component without worrying about any specifier (id, class, etc.) conflicts or styles ‘leaking out’ to other elements on the page.

This often leads to the belief that the reverse is true - that styles outside of the component won’t cross the Shadow boundary and ‘leak in’ to your component. However this is only partly true.

While specifiers do not leak in to your component (e.g. a color applied to an p element in a style rule outside of your component won’t effect any p elements in your Shadow DOM, although the rule will be applied to your Light DOM, or slotted content), inheritable styles applied to any elements containing your component will be applied to both your Shadow and Light DOM.

Inheritable styles

Inheritable styles are those that are defined on a parent that are then inherited by child elements. The most obvious inheritable styles are those defined on the html and body tags. Taking color as an example, if there is a color: green set on the body (which is a container for every element on the page), this will be inherited by all elements on the page, including Web Components, unless overriden by another more specific rule.

Inheritable styles are necessary so we don’t, for example, have to write a color rule on every element. But not all styles are inheritable, otherwise a border style on one element would be inherited by all its children:

Rules set in the Shadow DOM act in the same way - inheritable styles are applied to all children (Shadow and Light DOM), so adding a color: red to our Shadow DOM:

The chosen ones

So which styles are inheritable, and which are not? Well these are all defined by the CSS spec. The most common ones are:

color
cursor
direction
font
font-* (font-family, font-size etc.)
letter-spacing
line-height
text-align
text-indent
text-transform
visibility
word-spacing

So that’s why these styles do leak into your Web Component.

What if I don’t want my component to inherit from its parent?

Well you’re in luck, you can reset all inheritable styles for a component (Shadow and Light DOM) using all: initial, which resets the styles back to the CSS defaults or those defined in the browser ‘user agent stylesheet’. Note that outside specifiers matching in the Light DOM will not be reset.

What if I want to style my component from outside?

Well that’s where CSS custom properties come in, along with the new ::part and ::theme pseudo-elements, and I’ll cover that in an upcoming post.

If you have any feedback or questions I’d love to hear them @lamplightdev.

Subscribe to the mailing list to be notified of new posts about Web Components and building performant websites

How to pass data between Web Components?

Chris Haynes — Wed, 13 Mar 2019 00:00:00 +0000

A common question to those first experimenting with Web Components is how to communicate between different components on the same page. It might seem at first sight that the very thing Web Components are designed for - encapsulating DOM, CSS and behaviour inside of discrete elements - means that they are not suited to communicating outside their boundary with their fellow elements. But passing data is just a matter of using the standard JavaScript event model you’re already familiar with.

Part of the confusion may be due to the fact this topic is often left out of introductions to Web Components. Articles understandably concentrate on all the new functionality that Web Components provide, but the other great advantage they have is that they’re just an extension to the existing native web platform - all the techniques and APIs (old and new) of the web are available to you when building components.

JavaScript Event Model in Web Components

The native event model of the web consists simply of the dispatch and listening to of events using dispatchEvent and addEventListener, and the same methodology is used with Web Components.

A CustomEvent is a user defined event with a given name that can be sent from the component to the containing DOM using dispatchEvent:

// ...

onClick() {
  const myEvent = new CustomEvent('x-increment', {
    bubbles: true, // bubble event to containing elements
    composed: true, // let the event pass through the shadowDOM boundary
    detail: { // an object to hold any custom data that's attached to this event
      amount: 1,
    }
  });

  this.dispatchEvent(myEvent);
}

// ...

Note the composed property which needs to be set to enable the event to ‘escape’ the encapsulation of the ShadowDOM. Without this, the event would still be propagated up inside the shadowDOM, but no further.

The x-increment event can then be captured by any containing element using addEventListener, and any data extracted and used directly, or passed down to a child component:

// ...

constructor() {
  super();

  // attach shadowDOM here

  this.addEventListener('x-increment', (event) => {
    // extract data
    const { amount } = event.detail;

    console.log(amount); // 1

    // pass down to a child
    this.shadowRoot.querySelector('x-target').amount = amount;
  });
}

// ...

Managing state with a container component

A useful pattern to follow is to have a containing component that manages the application state by capturing child events and passing data back down the hierarchy. In this way state is always passed down the component tree in a uni-directional manner (a.k.a. one-way data binding) in a way that may be familiar from other UI frameworks.

Here’s a basic example that shows the above techniques in action to provide a simple counter. It consists of a x-controls component to hold the inputs, a x-counter component to show the output, and a x-container component to manage the application state and pass it down as properties to the other components.

In upcoming posts we’ll have a closer look at ways the above application can be improved by generalising the handling of properties, using a templating library to declaratively update the DOM and attach event handlers, managing styles in web components, and much more.

If you have any feedback or questions I’d love to hear them @lamplightdev.

Subscribe to the mailing list to be notified of new posts about Web Components and building performant websites