Skip to content

Instantly share code, notes, and snippets.

@sorvell
Last active April 14, 2026 00:37
Show Gist options
  • Select an option

  • Save sorvell/bd8dd397a2d5a7c950b65b5badc2604b to your computer and use it in GitHub Desktop.

Select an option

Save sorvell/bd8dd397a2d5a7c950b65b5badc2604b to your computer and use it in GitHub Desktop.
HTML Web Components Are a Lie

HTML Web Components Are a Lie

The idea is seductive since it embraces progressive enhancement to reach the widest possible audience with the best possible experience. You put real HTML inside a custom element, enhance it by defining the element with JS, and skip the Shadow DOM headaches. But it breaks the most basic contract of the DOM: elements can contain children, and those children can change. When they do, the component has no idea and all hell breaks loose. As defined, HTML web components aren't components, they are decorators for static content.

Honest HTML web components should use Declarative Shadow DOM. It preserves progressive rendering and slots are the only way to make dynamic composition actually work. It's not perfect yet, but the true grain of the web evolves through the hard work of establishing platform standards. It's tough but fundamental work in need of impassioned energetic developers. And along the way, a small amount of targeted JS can bridge gaps and show where the platform needs to go (hint: declarative custom elements).

Before you go... The web is a place where people build many amazing things. This criticism applies to custom elements that render elements into light DOM. If your component documents that it doesn't accept children, that's not dishonest, just a bit limited. You could even support something like render props to give users control. And if your requirements truly dictate light DOM rendering, so be it, but strongly consider highlighting this in the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment