3 Methods for Scoped Styles in Web Components That Work Everywhere

Web components are great. They’re versatile. They can be rendered on the server or (very much less preferably) on the client. They may or may not need interactivity or client-side JavaScript. And unlike heftier legacy frameworks like React, when you need to add interactivity they can still be extremely lightweight by leveraging (dare I say it…) The Platform™ *audible gasp*.

But let’s not get distracted from the task at hand: we want to evaluate a few different options on the table to apply styles (CSS) to our web components.

Here are the things we want to think about:

1. Encapsulation. We don’t want styles from distinct components to interfere with each other (that’s what this blog post is here for, after all).
2. Performance. Predictably, a method popularized for CSS encapsulation (CSS-in-JS) was less than ideal because it was slow-by-default. Let’s keep performance at the forefront of our minds.
3. Browser compatibility. Let’s not go so far out on the cutting edge that we leave some of our visitors behind.
4. Code re-use without duplication, during both authoring and the output. We want to streamline our output to avoid sending any more code down the wire than we need to.
5. Client-side framework independent. The methods described in this post do not use any client-side libraries or frameworks.

Methods for encapsulated styles:

1. Declarative Shadow DOM
2. Shadow DOM
3. WebC
4. Future bonus method: CSS @scope

1. Declarative Shadow DOM #

This is the newest kid on the block. And with Safari recently shipping support (in 16.4), only Firefox is now conspicuously missing from the evergreens.

<sample-component>
	Fallback content.
	<template shadowrootmode="open">
		Server rendered Declarative Shadow DOM.
		<style>
		:host {
			text-decoration: underline;
			text-decoration-color: red;
		}
		</style>
	</template>
</sample-component>

Note that the underline is restricted to the component and the component only as Declarative Shadow DOM styles are encapsulated for free by the platform! Awesome!

It’s also worth noting that Shadow DOM is not completely isolated from its host page—some styles are inherited! Chris Haynes elaborates in this 2019 post: Why is my Web Component inheriting styles?

The big drawback of Declarative Shadow DOM comes when you have multiple instances of the same component on the page: you need to duplicate the styles and template content in each instance (not ideal).

<sample-component>
	<!-- duplicated -->
	Fallback content.
	<template shadowrootmode="open">
		Server rendered Declarative Shadow DOM.
		<style>
		:host {
			text-decoration: underline;
		}
		</style>
	</template>
</sample-component>
<sample-component>
	<!-- duplicated -->
	Fallback content.
	<template shadowrootmode="open">
		Server rendered Declarative Shadow DOM.
		<style>
		:host {
			text-decoration: underline;
		}
		</style>
	</template>
</sample-component>

It’s worth noting that WebC can assist you when you’re authoring components with Declarative Shadow DOM so that you don’t have to duplicate this template content yourself!

Polyfill and Client-side JavaScript #

If you want to add additional clientside interactivity to the component, use the Custom Elements API to do so. This is recommended and required for Declarative Shadow DOM components in Firefox, currently lacking support and requiring a polyfill.

This is less than ideal, as it places a JavaScript dependency on CSS (in Firefox only).

<script>
if("customElements" in window) {
	customElements.define("sample-component", class extends HTMLElement {
		connectedCallback() {
			// polyfill (only applies if needed)
			polyfillDeclarativeShadowDom(this);
		}
	});
}
</script>

// Declarative Shadow DOM polyfill
// Supports both streaming (shadowrootmode) and non-streaming (shadowroot)
function polyfillDeclarativeShadowDom(node) {
	let shadowroot = node.shadowRoot;
	if(!shadowroot) {
		let tmpl = node.querySelector(":scope > template:is([shadowrootmode], [shadowroot])");
		if(tmpl) {
			// default mode is "closed"
			let mode = tmpl.getAttribute("shadowrootmode") || tmpl.getAttribute("shadowroot") || "closed";
			shadowroot = node.attachShadow({ mode });
			shadowroot.appendChild(tmpl.content.cloneNode(true));
		}
	}
}

Summary #

• Performance ★★★☆
  • ✅ Server rendered content.
  • ✅ No JavaScript requirement to apply encapsulated styles (except Firefox, keep reading).
• Compatibility ★★☆☆
  • This is a very new feature that just shipped in Safari.
  • ❌ (Temporary) Firefox requires a JavaScript polyfill, which means that Firefox does have a JS dependency on CSS.
• Duplication ★☆☆☆
  • ❌ Declarative Shadow DOM template markup is duplicated throughout every component instance. Whew! This is less than ideal but it’s important to remember that it’s still much faster than alternative CSS-in-JS methods.

2. Shadow DOM #

This method uses JavaScript to client-render markup into Shadow DOM. Here’s a code sample of how two instances of <sample-component> might look in your editor:

<sample-component>Fallback content.</sample-component>
<sample-component>Fallback content.</sample-component>
<template id="shadow-dom-template">
	Client-rendered Shadow DOM
	<style>
	:host {
		text-decoration: underline;
		text-decoration-color: green;
	}
	</style>
</template>
<script>
if("customElements" in window) {
	customElements.define("sample-component", class extends HTMLElement {
		connectedCallback() {
			let template = document.getElementById("shadow-dom-template");
			let shadowroot = this.attachShadow({ mode: "open" });
			shadowroot.appendChild(template.content.cloneNode(true));
		}
	});
}
</script>

Again the benefit here is that the styles applied do not leak out—they’re encapsulated by Shadow DOM—but we did need to use JavaScript to attach the styles.

Summary #

Client-rendering is limiting here. While I wouldn’t be so prescriptive to say that it isn’t useful (some features are secondary/optional after all, depending on your use case and requirements)—but it does heavily limit where the approach can be applied.

• Performance ★☆☆☆
  • ❌ Client rendered content.
  • ❌ JavaScript requirement to apply encapsulated styles.
• Compatibility ★★★☆
  • ✅❌ Very broad browser support but I gotta dock one star for JavaScript-generated content, which (even independent of performance) can have further implications for SEO et al.
• Duplication ★★★★
  • ✅ Only one instance of the template code is required on a page and can be re-used by every component instance.

3. WebC #

Haven’t heard of WebC? It’s a single file component format for Web Components—and it works great with Eleventy. Learn more on the WebC docs.

Consider a WebC component file sample-component.webc with the following content:

Server rendered HTML.
<style webc:scoped>
:host {
	text-decoration: underline;
	text-decoration-color: blue;
}
</style>

And on our page we’ll use it twice to show how it scales:

<sample-component>Fallback content.</sample-component>
<sample-component>Fallback content.</sample-component>

This is how the above template renders:

<style>.ws0ljrjcl{text-decoration:underline;text-decoration-color:blue}</style>
<sample-component class="ws0ljrjcl">Server rendered HTML.</sample-component>
<sample-component class="ws0ljrjcl">Server rendered HTML.</sample-component>

As you can see from the rendered code, the webc:scoped feature generates a component specific class name and adds that to the component for encapsulated styles. The class is shared across instances and the component CSS is only added once per page.

This allows you to author your component CSS without additional ceremony and WebC will compile it to CSS that has an extremely wide browser compatibility profile (working in Firefox without JS and even in legacy versions of the evergreens).

Client JavaScript #

WebC de-duplicates JS in the same way as CSS too. This means we can add <script> in the component file for our Custom Element client JavaScript and this code will only appear on the page once, no matter how many instances of the component exist on the page.

Server rendered HTML
<style webc:scoped>
:host {
	text-decoration: underline;
	text-decoration-color: blue;
}
</style>
<script>
if("customElements" in window) {
	window.customElements.define("sample-component", class extends HTMLElement {
		connectedCallback() {
			// Do more things
		}
	});
}
</script>

Summary #

I won’t give star ratings to something I built 😅 but I do think WebC allows folks to broaden access to things built with web components without the drawbacks of other methods!

• Performance
  • ✅ Server rendered content.
  • ✅ No JavaScript requirement to apply encapsulated styles.
• Compatibility
  • ✅ The broadest browser support.
• Duplication
  • ✅ The component code lives in the component file, editable in one place. The CSS only appears once on a page, independent of how many times you use the component.

It’s also worth noting here that Declarative Shadow DOM and Shadow DOM methods can be used with WebC too! Have a look at sample WebC components for each of the methods documented here on @11ty/demo-webc-shadow-dom.

4. CSS @scope #

While not currently available, platform-support for scoping without Shadow DOM may be coming and Miriam Suzanne is leading the charge!

Learn more:

• https://css.oddbird.net/scope/explainer/
• https://github.com/w3c/csswg-drafts/issues/5809
• https://drafts.csswg.org/css-cascade-6/#scoped-styles

Keep an eye on this method—it’s exciting!