Web components: custom elements, shadow DOM and where the encapsulation ends

What it is

Three browser features make up web components. Custom elements: a class extending HTMLElement, registered with customElements.define("x-name", Class) (the name must contain a hyphen), with connectedCallback, disconnectedCallback and attributeChangedCallback for the attributes listed in a static observedAttributes array. Shadow DOM: attachShadow({ mode: "open" }) gives the element a private subtree; MDN states that styles inside it are scoped to that tree, so page styles do not affect shadow elements and shadow styles do not affect the page, and <slot> projects light-DOM children into it. Templates: <template> holds inert markup, and <template shadowrootmode="open"> declares a shadow root in server-rendered HTML with no script.

Why it matters

Custom elements are the only component model the browser itself understands: they work in any framework or none, survive framework migrations and can be used from plain server-rendered HTML. The price is that the encapsulation is real, and every concern that crosses the boundary (theming, forms, labels, focus, events) needs an explicit opening.

How to apply

• Expose styling surfaces deliberately: custom properties for values (they inherit into the shadow tree), and part="label" on inner elements so the page can write x-name::part(label); MDN describes part as making a shadow element visible to the parent DOM.
• Make form controls real participants with static formAssociated = true and ElementInternals (setFormValue, setValidity); without this a custom input never submits a value.
• Prefer autonomous elements; MDN notes that Safari does not plan to support customized built-ins (is="...").
• Render initial state with declarative shadow DOM when first paint or crawlers matter, then upgrade with the class.
• Reflect important state as attributes so CSS and tests can select on it; keep mode: "open" (MDN says closed mode is not a strong security mechanism, only a signal).
• Style x-name:not(:defined) for the time before the script runs, so content does not jump on upgrade.

Pitfalls

ID references do not cross the boundary: a <label for> or aria-labelledby in the page cannot point at an input inside the shadow, so either slot the control in from light DOM or label it inside. Global resets, utility classes and icon sprites do not apply inside. Custom events need composed: true to be heard outside. Registering the same name twice throws, which bites when two bundles ship the same component. Dev tools show the shadow tree, but document.querySelector does not.