# Web Components

Each team ships its part as a custom element such as <team-b-cart>. The tag name, attributes and events are the contract, and Shadow DOM can keep each team's styles inside its element.

## How it works

1. **Shell places tags.** The shell's HTML contains each team's element, such as <team-b-cart sku="t-shirt">, before any team code has run.
2. **Load the definition.** Team B's script, served from its own deployment, calls customElements.define and the browser upgrades every matching tag.
3. **Render in its shadow root.** The element renders into a shadow root, so page selectors don't match inside it and its own styles don't leak out. Inherited properties such as font and color still pass in.
4. **Talk through the contract.** The shell passes data down as attributes; elements report back with DOM events that the shell and other teams listen for.

## Try it

**Demo: Style isolation.**

Team A ships .button { background: orange; border-radius: 0 } and body { font-family: Georgia, serif }, and Team B sets no font of its own. Without isolation, both rules are global: Team B's Pay now button turns orange and its text changes font. With CSS Modules, the class is renamed to something like .button_x7f2a, so Team B's button is safe, but body is a tag selector and stays global, so the font still changes. With Shadow DOM, selectors can't cross the shadow root, so the button is safe, but inherited properties such as the font still pass from the host into the shadow tree unless Team B resets them. With an iframe, Team B runs in its own document: neither rule reaches it, and nothing is shared either, at the cost of a whole extra page load.

Takeaway: Isolation is a spectrum, not a switch. CSS Modules scope class names but not global selectors. Shadow DOM blocks selectors, yet inherited properties like fonts still flow in. Only an iframe isolates everything, and it costs a whole page load.

## Pros

- A browser standard that works with any framework, or none.
- The tag name, attributes and events form a small, explicit contract between teams.
- Shadow DOM stops selectors at the element's boundary in both directions, without naming conventions.

## Cons

- Server rendering needs extra work; declarative Shadow DOM helps, but each team's framework must support producing it.
- Attributes are strings, so rich data has to go through properties or events, which frameworks wire up in different ways.
- Element names are global to the page unless an element uses a scoped registry, which is newly available and missing from older browsers.

## Best when

- Teams use different frameworks but need to share widgets.
- Embedding team-owned widgets into pages you don't control, such as a CMS.
- You want an explicit, standards-based contract instead of a shared runtime.

## Avoid when

- SEO-critical pages that must render fully on the server without extra setup.
- Most of the UI lives inside one framework that already composes well on its own.
- Your design system relies on global selectors that Shadow DOM would block.

## In code

`team-b/cart.js · shell.html`

```js
// Team B: define the element once, from its own deployment
class TeamBCart extends HTMLElement {
  static observedAttributes = ["sku"];

  constructor() {
    super();
    // Build the shadow tree once, even if the element moves
    this.button = document.createElement("button");
    this.button.addEventListener("click", () =>
      this.dispatchEvent(new CustomEvent("cart:added", { bubbles: true })));
    this.attachShadow({ mode: "open" }).append(this.button);
  }

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render();
  }

  render() {
    // textContent, not innerHTML: the attribute is never parsed as HTML
    this.button.textContent = `Add ${this.getAttribute("sku") ?? ""}`;
  }
}
customElements.define("team-b-cart", TeamBCart);

// Shell: <team-b-cart sku="t-shirt"></team-b-cart>
document.addEventListener("cart:added", () => console.log("updated"));
```

## Ratings

_Editorial judgement for a typical team, from 1 to 5._

- **Team independence: 3/5** (higher is better). Teams can deploy element scripts on their own, but nothing in the standard loads them at runtime, so independence depends on how you deliver those scripts.
- **Runtime performance: 3/5** (higher is better). Each team's script is another request, and teams that each bundle a framework ship it more than once.
- **Complexity: 3/5** (lower is simpler). The element API is small, but loading scripts, versioning tags and passing rich data are left to you.
- **SSR / SEO support: 2/5** (higher is better). Elements usually render in the browser; declarative Shadow DOM allows server output but needs support from each team's tooling.
- **Tech-agnostic: 4/5** (higher is better). Any framework can render or wrap a custom element, though frameworks differ in how they pass properties and handle events.
- **Isolation: 4/5** (higher is better). Shadow DOM keeps selectors and markup apart in both directions, but inherited styles and custom properties pass in, and scripts and element names still share one page.
- **UX consistency: 3/5** (higher is better). Global selectors stop at the shadow boundary, so a shared design system has to be built into every element, or passed in as CSS custom properties, which do cross it.
- **Tooling maturity: 4/5** (higher is better). Supported natively by browsers and well documented, with libraries available to cut boilerplate.

## Tooling and ecosystem

Custom elements and Shadow DOM are web platform standards documented on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements), so there is no version to track. What changes is browser support for newer features. Declarative Shadow DOM (`<template shadowrootmode="open">`), which lets a server send an element's shadow tree as HTML, has worked across browsers since February 2024 and MDN now lists it as widely available. Scoped custom element registries (`new CustomElementRegistry()`), which let a shadow root define element names without clashing with the rest of the page, became Baseline in October 2026 ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/CustomElementRegistry)). They are newly available, so older browsers still in use don't support them.

Michael Geers' [micro-frontends.org](https://micro-frontends.org/) uses custom elements as the **integration contract** between teams: the tag name, its attributes and its events are the public API. A common convention is to prefix every element with the team's name. In the global registry (`window.customElements`), a name can be defined only once per page, so two versions of one element can't both be defined there. A scoped registry attached to a shadow root lets each team define its own version under the same name inside its own element.

## Sources

- [Using custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements), MDN Web Docs
- [Using shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM), MDN Web Docs
- [CustomElementRegistry: CustomElementRegistry() constructor](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/CustomElementRegistry), MDN Web Docs
- [Micro Frontends – extending the microservice idea to frontend development](https://micro-frontends.org/), Michael Geers · micro-frontends.org

https://microfrontends.dev/approaches/web-components