Scoped CustomElementRegistry polyfill prototype

🚨 Work in progress

This polyfill explores implementation of a non-finalized spec proposal and is currently a work in progress.

Overview

Scoped CustomElementRegistry polyfill based on Scoped Custom Element Registries WICG proposal.

Technique: uses native CustomElements to register stand-in classes that delegate to the constructor in the registry for the element's scope; this avoids any manual treewalks to identify custom elements that need upgrading. Constructor delegation is achieved by constructing a bare HTMLElement, inspecting its tree scope (or the tree scope of the node it was created via) to determine its registry, and then applying the "constructor call trick" to upgrade it.

Notes/limitations:

• In order to leverage native CE when available, observedAttributes handling must be simulated by patching setAttribute/getAttribute/toggleAttribute to call attributeChangedCallback manually, since while we can delegate constructors, the observedAttributes respected by the browser are fixed at define time. This means that native reflecting properties are not observable when set via properties.
• In theory, this should be able to be layered on top of the Custom Elements polyfill for use on older browsers, although this is yet to be tested. Use of Reflect.construct may need to be modified in those cases

Outstanding TODOs:

• <input disabled="" type="checkbox"> #419: Convert source to TS (to match convention in this monorepo)
• <input disabled="" type="checkbox"> #420: Test and work out layering strategy with standard custom-elements polyfill
• <input disabled="" type="checkbox"> #421: Test and work out layering strategy with shady-dom & shady-css polyfills
• <input disabled="" type="checkbox"> #422: Add benchmarks

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.0.10] - 2025-02-26

Added

• Added support for ShadowRoot.prototype.createElementNS()

• Added the registry property to ShadowRootInit to match current proposal. customElements remains supported for compatibility

Changed

• polyfill always used; conditional installation blocked by need for spec

• formAssociated set by first name's defining value or if CustomElementRegistryPolyfill.formAssociated set contains name

Fixed

• Fixed a bug in versions of WebKit and Safari that had the prototype scoped custom element registry implementation enabled.

• parser created custom elements call attributeChangedCallback for parser created attributes

• toggleAttribute called only when attribute value changes

[0.0.9] - 2023-03-30

• Update dependencies (#542)

[0.0.8] - 2023-02-03

Fixed

• toggleAttribute polyfill now retains the force argument if it is present

[0.0.7] - 2023-01-06

Fixed

• Polyfilled ElementInternals prototype methods now return their original value.

[0.0.5] - 2022-02-18

Fixed

• Replaced self with typeof globalThis === 'object' ? globalThis : window for compatibility with Node (for SSR).

[0.0.4] - 2022-01-27

Fixed

• Bump @web/test-runner and related deps to resolve issue running tests on Chrome
• Make form-associated tests conditional on the native feature.
• Fixed form-associated custom element definitions (static formAssociated = true) when used with the polyfill.
• Fixed patched callback names in form-associated custom element support.
• Fixed handling of mixed-case attributes. Fixes #483

[0.0.3] - 2021-08-02

• Maintenance release (no user-facing changes)

[0.0.2] - 2021-06-02

• Fix to allow definition of custom elements whose classes have been created before applying the polyfill.
• Run connectedCallback on upgraded elements. Fixes #442.
• Checks if ShadowRoot prototype supports the createElement method to determine if the polyfill should be applied or not.

[0.0.1] - 2021-02-18

• First public prerelease.