Forem: Poul H. Hansen

You might not need shadow DOM

Poul H. Hansen — Thu, 23 Apr 2020 18:51:29 +0000

When talking about Web Components we often forget that it´s an umbrella term that covers a set of low level API's that work together to form the web´s native component model.

It is a very common misconception that we need to use them all in order to build Web Components.

In fact, we really only need the custom element API in order to register our component name and class with the browser. However, combining custom elements with shadow DOM gives us out-of-the-box style isolation and DOM encapsulation, which is perfect for self-contained reusable components for our UIs.

Creating a Web Component that does not use shadow DOM is perfectly fine, and in some cases, i´d advise against using shadow DOM at all.

Let us go over some use-cases where I think shadow DOM might not be the right choice. But before that, a quick overview of what shadow DOM provides.

The short intro to shadow DOM

Shadow DOM is all about encapsulation. Due to the global nature of HTML, CSS and Javascript we´ve developed a lot of tools and methodologies to circumvent the issues over the years.

Common issues include clashing element Id´s, classes or styles from the global stylesheet overriding 3rd party libraries and/or vice versa. Some of us still have to keep these things in mind when developing today depending on tooling.

Shadow DOM fixes this by giving us:

Isolated DOM tree: The shadow DOM is self-contained and the outside cannot query elements on the inside (e.g. document.querySelector wont return nodes from within the shadow tree)
Scoped CSS: Styles defined within the shadow DOM will not leak out, and outside styles will not bleed in.
Composition: Through the use of <slot /> our elements can take outside nodes from the light DOM and place them in specific positions inside the shadow DOM.

The scoped CSS alone is incredibly powerful. Frameworks today all include some form of scoped styling that, during compile time, adds an attribute to the DOM element that is also added to the output CSS. This combination results in a very specific selector in your css (a[data-v-fxfx-79]) that won´t bleed out and affect the outside DOM.

However, this method does not prevent outside styles from leaking into your component. This is where the true power of shadow DOM scoped styling really shines. Not only is it native to the browser, but it works both ways.

So why not always use shadow DOM? 🤔

We´ve just learned that the shadow DOM API gives us a set of incredibly powerful tools that enable us to build truly encapsulated reusable components. So why not use it everywhere?

First of all, without a clear goal or use-case in our mind, we probably shouldn't just jump the gun and start enabling shadow DOM everywhere. As with every new technology, we should first do our research.

Browser support

Whenever we look at cool new browser API´s we have to also take support into consideration. Luckily, shadow DOM is supported in all major browsers. However, some of us has to still support older browser like IE11 for a while still.

We could polyfill for our IE11 users, right? 🤷‍♂️

While polyfilling shadow DOM is possible, it is pretty hard, and the existing polyfills are invasive and slow.

So instead of directly polyfilling the shadow DOM, compilers such as stencilJS fall back to scoped styles for IE11. While this does make our component usable, it also reintroduces the issue of scoped styling not preventing outside styles from bleeding in.

This means that we have to cautiously test in IE11 that outside styles won´t affect the insides of our component. That sucks, as our component now behaves differently between browsers.

So even though your components might be great candidates for shadow DOM, carefully weigh your options if you´re forced to support IE11.

Who are our consumers?

The next thing I suggest looking into is, who are we making these components for? Is it our own internal product or are we making a component library to be consumed by the masses on npm ?

A friend of mine said it quite well; A single component that needs to stand on its own with its own set of functionality is a good candidate for shadow DOM. While one or more components as part of an application might not need shadow DOM, as their intended use is much clearer and their markup less fragile.

The quote above got me thinking about the whole internal vs external thing. When introducing web components to an existing long running project, there is a good chance we already have some sort of design system in place already. Or at the very least, an extensive set of battle tested styles and markup.

With this in mind, we should really think about what shadow DOM could solve for us that we haven´t already solved by using methodologies such as BEM or ITCSS, or just a solid CSS structure.

Say we have the following classes in our design system stylesheet:

    .card {...}
    .card__header {...}
    .card__body {...}
    .card__footer {...}

Now let us add a new reusable component to the project:

@Component({
    tag: 'fancy-card',
    shadow: true
})
export class FancyCardComponent {
    render() {
        return (
            <Host class="card">
                <div class="card__header">
                    <slot name="header"></slot>
                </div>
                <div class="card__body">
                    <slot></slot>
                </div>
                <div class="card__footer">
                    <slot name="footer"></slot>
                </div>
            </Host>
        )
    }
}

💡 I´m using stencil, a web component compiler, in my example above

At first glance we might expect our new <fancy-card> component to just work. We´ve added the classes from our stylesheet, they worked before we added the component, so all is good, right?

Not exactly...

When we see the element in the browser, the only style applied will be from the .card class on the <fancy-card> element. This is because the element has a shadow root attached to the host element (<fancy-card>), and as such, the divs within the component cannot be styled via CSS classes defined outside the component shadow root.

Remember how global styles won´t bleed into the shadow DOM? Well, this is how it works.

We have no way of using our existing classes unless we refactor and include those styles inside the component shadow root. If the existing design system relies on sass variables, we´d also need to import those in the component stylesheet.

While refactoring itself is not a problem, as we do it all the time, the reason for which we are refactoring is. By moving the above HTML and CSS into the component, we haven´t solved anything that wasn´t already solved before.

Now, I´m aware that the <fancy-card> component might seem like a dumb example at first glance, but I´ve actually seen a lot of these components out there. In fact, I´ve done it myself when I first started looking into Web Components and thought I needed to convert everything.

The solution to the above could instead be to turn off shadow DOM. The issue of the class styles not being applied inside the component would go away and we would still have a composable component ready to use.

<fancy-card>
    <h2 slot="header">Awesome product</h2>
    <p>lorem ipsum...</p>
    <button slot="footer">Buy</button>
</fancy-card>

Stencil enables using <slot> without shadow DOM enabled. In a vanilla web component the above markup would not work as natively, <slot> is part of the shadow DOM API.

Some would probably argue that with the rather simple markup for the component and no complex functionality, it should not require javascript at all. Since it is merely a glorified div element. While I do agree that such a simple component should not require javascript, if it was to be part of a consumable component library, using it would be a lot easier than having to add the html structure plus the classes as a consumer. As long as we´re aware of the trade-offs!

A note on forms

In a previous article, Custom elements, shadow DOM and implicit form submission, I mentioned that we cannot query the shadow tree from the outside, elements such as input or textarea placed inside our shadow root will not work with an outside <form> element. The inputs would simply be ignored as they are not in the same tree-order as the form.

So if we wanted to create a custom input component. We would have to either write custom functionality to circumvent this issue or...

🥁🥁🥁

Just not use shadow DOM 🤷‍♂️

Conclusion

Ultimately, shadow DOM is not a requirement in order to build Web Components. However, the great synergy between shadow DOM, custom elements and CSS variables is worth exploring. There are already tons of great projects and stand-alone components out there that show the power and versatility of these API´s combined.

I hope my post helped clear some of the confusion around shadow DOM and how it can help us tremendously when building Web Components.

Using the url for state with Angular

Poul H. Hansen — Sat, 29 Feb 2020 22:19:55 +0000

A pretty common use-case for storing values in the url in the form of query strings are filters.
Storing filters in the url ensures that everyone with the link will see the same filterable content in their browsers.

This is really great for ecommerce where people will often discuss with friends or ask for help before purchasing a product, and in doing so, might send a link of their filtered products along to their friends.

While it may seem like a small thing, it´s actually a really great user experience to store product filters in the url.

If users refresh their browser by hitting F5, they will also return back to the same screen they were on before. Neat!

But what about single page applications? 🤔

Typically, in a SPA, routing happens on the client. Meaning our frameworks or libraries hook into the browser history, altering the state and updating the url without a full page refresh.
There is no roundtrip to the server and the whole page does not need to be rendered all over, which in itself, is also really nice!

However, since the url in this case is really only responsible of getting the application resources to the user upfront, it is not used for fetching any related data for the route.

In Angular we normally use services to fetch data. These services are then imported into our components which use these services to fetch data and render the view:

@Component({
  selector: 'product-list',
  template: `
  <ul>
      <li *ngFor="let product of products">{{ product.name }} {{ product.genre }} {{ product.platform }}</li>
  </ul>
  `
})
export class ProductListComponent implements OnInit {
  products: Product[] = [];

  constructor(private service: ProductService) {}

  ngOnInit() {
      this.service.getProducts().subscribe(_products => {
          this.products = _products;
      })
  }
}

The example above is pretty simple. We inject the ProductService and during the ngOnInit lifecycle of the component, we subscribe to getProducts() which returns
a list of products when the api call is done. The response, a list of products in our case, is then set to the class field products.

This field is then used in the template to render the list of products in a normal unordered list.

Adding filters 💡

Now lets say that we want to add two types of filters to our product list, genre and platform, to narrow down the list of games.

Instead of storing the filter options on the component or in a service, let us use the url instead and store our filters as query params.

To access the query params we use the ActivatedRoute service within our component.
And to update the query params, we simply navigate 🤭 -- yeah, it is that simple!

Getting the query params look something like:

constructor(private route: ActivatedRoute) {}

ngOnInit() {
    this.route.queryParams.subscribe(queryParams => {
        /**
         * If the query-string is '?genre=rpg&platform=xbox'
         * the queryParams object will look like
         * { platform: 'xbox', genre: 'rpg }
         * */
    });
}

Depending on where you´re navigating from, setting query parameters can be done in a few different ways:

<button [routerLink]="[]" [queryParams]="{ genre: 'rpg' }" queryParamsHandling="merge">RPG</button>

Here we use the routerLink directive on a button to navigate to the same route as we´re on using [routerLink]="[]" and set the query parameter genre to rpg, using the queryParams property.

We use the queryParamsHandling="merge" here to make sure we merge our queryParams with the already existing queryParams, overriding ones with identical keys.

So clicking another routerLink that has [queryParams]="{ genre: 'racing' }" will directly override our current genre query param, but a routerLink with [queryParams]="{ platform: 'xbox' }" would merge the two into [queryParams]="{ genre: 'rpg', platform: 'xbox' }".

Another option is doing it from within a component method using the router service:

constructor(private router: Router) {}

updateQueryParameters() {
    this.router.navigate(
        [], 
        { 
            queryParams: { 
                genre: 'rpg'
            }, 
            queryParamsHandling: 'merge' 
        }
    );
}

Using the router.navigate function we navigate to the current route [] and set the queryParams object and the queryParamsHandling option, just like we did with the directive.

For the purpose of this example i´ll be using simple links to update the filters like so:

<div class="product-filters">
    <p>genres: </p>
    <a [routerLink]="[]" [queryParams]="{ genre: 'rpg' }" queryParamsHandling="merge">rpg</a>
    <a [routerLink]="[]" [queryParams]="{ genre: 'platformer' }" queryParamsHandling="merge">platformer</a>
    <a [routerLink]="[]" [queryParams]="{ genre: 'racing' }" queryParamsHandling="merge">racing</a>
    <a [routerLink]="[]" [queryParams]="{ genre: null }" queryParamsHandling="merge">clear</a>
</div>

<div class="product-filters">
    <p>platforms: </p>
    <a [routerLink]="[]" [queryParams]="{ platform: 'playstation' }" queryParamsHandling="merge">playstation</a>
    <a [routerLink]="[]" [queryParams]="{ platform: 'switch' }" queryParamsHandling="merge">switch</a>
    <a [routerLink]="[]" [queryParams]="{ platform: 'xbox' }" queryParamsHandling="merge">xbox</a>
    <a [routerLink]="[]" [queryParams]="{ platform: null }" queryParamsHandling="merge">clear</a>
</div>

Above i´ve added an extra button to each list of filters to clear that particular filter from the url, by simply setting null

Now, clicking on the link for platformer under genres, followed by the link to xbox under platforms we end up with a url like this:

localhost:4200/?genre=platformer&platform=xbox

Great, now we can set our filters in the url and have our component listen to these changes using the ActivatedRoute service. So far so good!

Putting it all together

Let us combine our productService with our queryParams observable stream from the ActivatedRoute service to make sure the service is called each time our filters are updated.

@Component({
  selector: 'product-list',
  templateUrl: './product-list.component.html'
})
export class ProductListComponent {

  products$: Observable<Product[]>;

  constructor(private route: ActivatedRoute, private productService: ProductsService) {
    this.products$ = this.route.queryParams.pipe(switchMap(params => {
      const filters = {
        platform: params.platform || "",
        genre: params.genre || ""
      };

      return this.productService.getProducts(filters);
    }));
  }
}

We´ve changed our class field products: Product[] to products$: Observable<Product[]> as it will now be an observable stream of data that gets updated when our filters update.

We then listen to changes on the queryParams stream from the ActivatedRoute service and and use switchMap to switch to the productService.getProducts observable, passing in the filters we get from the queryParams.

Since our queryParams could be non-existent we create an object and set default values to "" for both genre and platform to make sure we provide a sensible default.

The updated template for the ProductListComponent now looks like:

<ul>
    <li *ngFor="let product of products$ | async;">{{ product.name }} {{ product.genre }} {{ product.platform }}</li>
</ul>

Now, everytime we update a query parameter using one or more of our filters, the list of products will automatically get updated with new data from the service.

That is pretty much all there is to it! 🎉

An added benefit of using the url for state such as this, is that the component that updates the filters does not need to be directly tied to the component showing the product list.
They could live in completely separate parts of our application.

For those using a state management library such as ngrx, this might seem familiar.
Updating the query parameters here is much like dispatching an action, and listening to changes in the queryParams state of the url using the router, is like listening to store changes with selectors in ngrx.

Show me the code 💻

I have created an example repository for the ProductListComponent example used in this article, you can find it here: query-params-filter

I hope this has been useful to you in one way or another! 🙌

Also posted on my personal blog