Web Components

What it is

Web Components are a set of web standards enabling creation of custom, reusable HTML elements with style and behavior encapsulation. They work in any framework — or without one.

Standards

Web Components are based on three W3C/WHATWG specifications that work together:

• Custom Elements: API for registering new HTML elements with their own lifecycle (connectedCallback, disconnectedCallback, attributeChangedCallback)
• Shadow DOM: encapsulated DOM tree that isolates styles and markup from the main document
• HTML Templates: <template> and <slot> elements for reusable declarative content

Native custom element

class UserCard extends HTMLElement {
  static observedAttributes = ["name", "role"];
 
  constructor() {
    super();
    this.attachShadow({ mode: "open" });
  }
 
  connectedCallback() {
    this.render();
  }
 
  attributeChangedCallback() {
    this.render();
  }
 
  render() {
    const name = this.getAttribute("name") ?? "Unknown";
    const role = this.getAttribute("role") ?? "";
    this.shadowRoot.innerHTML = `
      <style>
        :host {
          display: block;
          padding: 1rem;
          border: 1px solid #333;
          border-radius: 8px;
          font-family: system-ui;
        }
        :host([highlighted]) { border-color: #58a6ff; }
        .name { font-weight: 600; }
        .role { color: #888; font-size: 0.875rem; }
      </style>
      <span class="name">${name}</span>
      <span class="role">${role}</span>
    `;
  }
}
 
customElements.define("user-card", UserCard);

Usage in HTML:

<user-card name="Ana García" role="Staff Engineer" highlighted></user-card>

The :host selector styles the element itself. :host([highlighted]) responds to attributes. Styles inside the Shadow DOM don't affect the rest of the page and vice versa.

Example with Lit

Lit simplifies authoring by eliminating the native API boilerplate:

import { LitElement, html, css } from "lit";
import { property } from "lit/decorators.js";
 
class UserCard extends LitElement {
  static styles = css`
    :host { display: block; padding: 1rem; border: 1px solid #333; border-radius: 8px; }
    .name { font-weight: 600; }
    .role { color: #888; font-size: 0.875rem; }
  `;
 
  @property() name = "";
  @property() role = "";
 
  render() {
    return html`
      <span class="name">${this.name}</span>
      <span class="role">${this.role}</span>
    `;
  }
}
 
customElements.define("user-card", UserCard);

Lit adds declarative reactivity, tagged template literal templates, and a typed property system — all in roughly 5 KB.

Framework interoperability

The key distinction is that Web Components use HTML attributes (strings) and JavaScript properties (any type). Frameworks that distinguish between both — like Vue and Svelte — have better interoperability than those that treat everything as attributes.

When to use

• Components shared across different frameworks
• Micro frontends with mixed technologies
• Framework-agnostic design systems
• Embeddable widgets on third-party sites

Frameworks based on Web Components

Limitations

• Shadow DOM and external CSS: global styles (Tailwind, CSS frameworks) don't penetrate the Shadow DOM — use CSS custom properties or ::part() to expose styling hooks
• Limited SSR: Declarative Shadow DOM exists but support in SSR frameworks is incomplete; hydration requires care
• Accessibility: Shadow DOM can break screen reader navigation if ARIA roles and focus order aren't managed correctly
• Verbose API: without Lit or another framework, the boilerplate for reactivity and templates is considerable

Why it matters

Web Components solve a problem that frameworks cannot: components that work in any context without runtime dependencies. For design systems that must serve teams using React, Vue, and Angular simultaneously, they are the only option that doesn't force a migration. The tradeoff is clear — more boilerplate and less ergonomics than a framework, but zero coupling and compatibility guaranteed by the browser.

References

• Web Components — MDN — MDN, 2024. Complete reference documentation for the standards.
• Custom Elements Specification — WHATWG, 2024. Official Custom Elements specification in the HTML Living Standard.
• Custom Elements v1 — web.dev — Google, 2024. Practical Custom Elements guide with examples.
• Lit — Google, 2024. Lightweight library for creating Web Components with declarative reactivity.
• Using Shadow DOM — MDN — MDN, 2024. Shadow DOM guide for style and markup encapsulation.