Document scoped customElementRegistry and related properties by pepelsbey · Pull Request #43149 · mdn/content

pepelsbey · 2026-02-17T13:01:41Z

Description

New pages

API/CustomElementRegistry/CustomElementRegistry — The CustomElementRegistry() constructor
API/CustomElementRegistry/initialize — The initialize() method
API/Document/customElementRegistry — The customElementRegistry property on Document
API/Element/customElementRegistry — The customElementRegistry property on Element
API/ShadowRoot/customElementRegistry — The customElementRegistry property on ShadowRoot
API/HTMLTemplateElement/shadowRootCustomElementRegistry — The shadowRootCustomElementRegistry property on HTMLTemplateElement

Updated pages

API/CustomElementRegistry — Added constructor section and initialize() to the list of instance methods
API/ShadowRoot — Added customElementRegistry to the list of instance properties
API/HTMLTemplateElement — Added shadowRootCustomElementRegistry to the list of instance properties
HTML/Reference/Elements/template — Added shadowrootcustomelementregistry to the list of <template> attributes

Motivation

Document the scoped custom element registries API supported in Safari 26 and Chrome Canary

Additional details

⚠️ The <template shadowrootcustomelementregistry> attribute is not currently listed in BCD but I tested and it seems to work in Safari and Chrome Canary.

github-actions · 2026-02-17T13:03:19Z

Preview URLs (17 pages)

Flaws (10)

Note! 13 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/API/CustomElementRegistry/upgrade
Title: CustomElementRegistry: upgrade() method
Flaw count: 3

macros:
- Macro domxref produces link /en-US/docs/Web/API/HTMLElement/connectedCallback which doesn't resolve
- Macro domxref produces link /en-US/docs/Web/API/HTMLElement/observedAttributes which doesn't resolve
- Macro domxref produces link /en-US/docs/Web/API/HTMLElement/attributeChangedCallback which doesn't resolve

URL: /en-US/docs/Web/API/ShadowRoot
Title: ShadowRoot
Flaw count: 1

macros:
- Macro domxref produces link /en-US/docs/Web/API/ShadowRoot/getSelection which doesn't resolve

URL: /en-US/docs/Web/API/Web_components
Title: Web Components
Flaw count: 3

macros:
- Macro defaultapisidebar produces link /en-US/docs/Web/Web_Components/Using_custom_elements which is a redirect
- Macro defaultapisidebar produces link /en-US/docs/Web/Web_Components/Using_shadow_DOM which is a redirect
- Macro defaultapisidebar produces link /en-US/docs/Web/Web_Components/Using_templates_and_slots which is a redirect

URL: /en-US/docs/Web/API/Web_components/Using_custom_elements
Title: Using custom elements
Flaw count: 3

macros:
- Macro defaultapisidebar produces link /en-US/docs/Web/Web_Components/Using_custom_elements which is a redirect
- Macro defaultapisidebar produces link /en-US/docs/Web/Web_Components/Using_shadow_DOM which is a redirect
- Macro defaultapisidebar produces link /en-US/docs/Web/Web_Components/Using_templates_and_slots which is a redirect

(comment last updated: 2026-02-20 16:45:28)

files/en-us/web/api/document/customelementregistry/index.md

hamishwillee · 2026-02-20T00:06:31Z

files/en-us/web/api/customelementregistry/index.md

 {{APIRef("Web Components")}}

-The **`CustomElementRegistry`** interface provides methods for registering custom elements and querying registered elements. To get an instance of it, use the {{domxref("window.customElements")}} property.
+The **`CustomElementRegistry`** interface provides methods for registering custom elements and querying registered elements. To get an instance of it, use the {{domxref("window.customElements")}} property. To create a scoped registry, use the {{domxref("CustomElementRegistry.CustomElementRegistry()", "CustomElementRegistry()")}} constructor.


" To get an instance of it, use the {{domxref("window.customElements")}} property. " is now not the only way.

files/en-us/web/api/htmltemplateelement/shadowrootcustomelementregistry/index.md

hamishwillee · 2026-02-20T00:10:37Z

files/en-us/web/api/shadowroot/customelementregistry/index.md

+
+A shadow root's `customElementRegistry` determines which [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements) definitions are used for upgrading elements within that shadow tree. It can be set when the shadow root is created via the `customElementRegistry` option of {{domxref("Element.attachShadow()")}}, or later using {{domxref("CustomElementRegistry.initialize()")}}. Once set to a `CustomElementRegistry` object, it cannot be changed.
+
+This property is also available on {{domxref("Document")}} objects via the same `customElementRegistry` property name.


If you accepted my comment on the Window variant of this property, make customElementRegistry a cross link.

hamishwillee · 2026-02-20T00:16:30Z

files/en-us/web/api/customelementregistry/initialize/index.md

+
+{{APIRef("Web Components")}}
+
+The **`initialize()`** method of the {{domxref("CustomElementRegistry")}} interface associates this registry with a DOM subtree, setting the {{domxref("Element.customElementRegistry", "customElementRegistry")}} of each inclusive descendant that doesn't already have one, and attempting to upgrade any [custom elements](/en-US/docs/Web/API/Web_components/Using_custom_elements) found.


My only concern here is that I don't know what upgrading is. Further down you link to https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/upgrade but that doesn't say what upgrading actually does either.

IN theory it is out of scope but you lean heavily on the definition, so if you are able would love a fix to https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/upgrade

hamishwillee · 2026-02-20T00:21:49Z

files/en-us/web/api/customelementregistry/customelementregistry/index.md

+
+The **`CustomElementRegistry()`** constructor creates a new {{domxref("CustomElementRegistry")}} object for scoped usage.
+
+The global `CustomElementRegistry` object associated with a {{domxref("Window")}} is not created using this constructor; it is automatically created when the window is set up, and is accessible via the {{domxref("window.customElements")}} property. The `CustomElementRegistry()` constructor is specifically for creating scoped registries that limit [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements) definitions to a particular scope.


IMO This should be inverted, and you should explain what you mean by scope. So something like

Suggested change

The global `CustomElementRegistry` object associated with a {{domxref("Window")}} is not created using this constructor; it is automatically created when the window is set up, and is accessible via the {{domxref("window.customElements")}} property. The `CustomElementRegistry()` constructor is specifically for creating scoped registries that limit [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements) definitions to a particular scope.

The constructor is specifically used for creating scoped registries that limit [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements) definitions to a particular scope, such as an element or {{domxref("ShadowRoot")}}.

Note that the global `CustomElementRegistry` object associated with a {{domxref("Window")}} is not created using this constructor; it is automatically created when the window is set up, and is accessible via the {{domxref("window.customElements")}} property.

hamishwillee

@pepelsbey Love this. Just a few suggestion.

I do think we should update https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements to at least mention this, and possibly also the top level https://developer.mozilla.org/en-US/docs/Web/API/Web_components

Were you planning on doing that?

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

pepelsbey · 2026-02-20T16:37:05Z

@hamishwillee good points! There you go:

Ouch, it was M, now it’s L 😬

hamishwillee · 2026-02-22T22:29:34Z

files/en-us/web/api/customelementregistry/upgrade/index.md


 None ({{jsxref("undefined")}}).

+## Description


This is so useful!

hamishwillee

@pepelsbey Looks great, and as a bonus I learned about uprading, which I had been fuzzy on.

* upstream/main: (619 commits) Fix usage of numbers iterator in zip example (mdn#43236) Synchronize with BCD v7.3.3 (mdn#43178) Add Firefox 148 sanitizer release note (mdn#43234) WebDriver conformance changes for Firefox 148 (mdn#43228) ci(auto-merge): fix target-repo (mdn#43139) Add session mgt guide (mdn#42908) docs(firefox-release): Finalize release notes for Fx148 release (mdn#43225) [Technical Review] Add folder for WebDriver BiDi and create initial landing pages (mdn#43153) fix: correct 'after' to 'before' in break-before always/all descriptions (mdn#43185) added the release note for position-try-order (mdn#43223) Clarify that role="button" does not inherit button functionality (mdn#43186) Fix wording mistake in Temporal.ZonedDateTime (mdn#43188) Fix description for break-before: always (mdn#43190) improve confusing sentance (mdn#43172) Document scoped customElementRegistry and related properties (mdn#43149) fix: correct terminology for object initializer property names (mdn#43182) Fix typo about arrow function expression body (mdn#43175) Update InterfaceData based on WebRef (mdn#43179) Fix clarify visibilitychange event intro to mention all triggers (mdn#43177) [WebExtensions] Document runtime.getVersion() method (mdn#42971) ...

Document scoped customElementRegistry and related properties

5733bc2

pepelsbey requested review from a team as code owners February 17, 2026 13:01

pepelsbey requested review from hamishwillee and removed request for a team February 17, 2026 13:01

github-actions bot added Content:HTML Hypertext Markup Language docs Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Feb 17, 2026

hamishwillee reviewed Feb 20, 2026

View reviewed changes

files/en-us/web/api/document/customelementregistry/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 20, 2026

View reviewed changes

files/en-us/web/api/htmltemplateelement/shadowrootcustomelementregistry/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Feb 20, 2026

View reviewed changes

pepelsbey and others added 4 commits February 20, 2026 08:03

Update index.md

01741cc

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Apply suggestions from code review

0d2c1c6

Mention scoped registries in the custom elements guide

0425e49

Mention custom registries in the web components overview

ccfa223

github-actions bot added size/l [PR only] 501-1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Feb 20, 2026

pepelsbey requested a review from hamishwillee February 20, 2026 16:37

Wrap “not useful” notes for template attributes into callouts

8df6c63

hamishwillee reviewed Feb 22, 2026

View reviewed changes

hamishwillee approved these changes Feb 22, 2026

View reviewed changes

hamishwillee merged commit 9c4d4cb into mdn:main Feb 22, 2026
8 checks passed

hamishwillee mentioned this pull request Feb 24, 2026

Missing scoped custom element registries docs #43237

Open

pepelsbey deleted the custom-element-registry branch February 27, 2026 15:31

jdatapple pushed a commit to jdatapple/content that referenced this pull request Mar 6, 2026

Document scoped customElementRegistry and related properties (mdn#43149)

52f24a0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document scoped customElementRegistry and related properties#43149

Document scoped customElementRegistry and related properties#43149
hamishwillee merged 6 commits intomdn:mainfrom
pepelsbey:custom-element-registry

pepelsbey commented Feb 17, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

hamishwillee Feb 20, 2026

Uh oh!

Uh oh!

hamishwillee Feb 20, 2026

Uh oh!

hamishwillee Feb 20, 2026 •

edited

Loading

Uh oh!

hamishwillee Feb 20, 2026

Uh oh!

hamishwillee left a comment

Uh oh!

pepelsbey commented Feb 20, 2026 •

edited

Loading

Uh oh!

hamishwillee Feb 22, 2026

Uh oh!

hamishwillee left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		A shadow root's `customElementRegistry` determines which [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements) definitions are used for upgrading elements within that shadow tree. It can be set when the shadow root is created via the `customElementRegistry` option of {{domxref("Element.attachShadow()")}}, or later using {{domxref("CustomElementRegistry.initialize()")}}. Once set to a `CustomElementRegistry` object, it cannot be changed.

		This property is also available on {{domxref("Document")}} objects via the same `customElementRegistry` property name.


		{{APIRef("Web Components")}}

		The `initialize()` method of the {{domxref("CustomElementRegistry")}} interface associates this registry with a DOM subtree, setting the {{domxref("Element.customElementRegistry", "customElementRegistry")}} of each inclusive descendant that doesn't already have one, and attempting to upgrade any [custom elements](/en-US/docs/Web/API/Web_components/Using_custom_elements) found.


		The `CustomElementRegistry()` constructor creates a new {{domxref("CustomElementRegistry")}} object for scoped usage.

		The global `CustomElementRegistry` object associated with a {{domxref("Window")}} is not created using this constructor; it is automatically created when the window is set up, and is accessible via the {{domxref("window.customElements")}} property. The `CustomElementRegistry()` constructor is specifically for creating scoped registries that limit [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements) definitions to a particular scope.

-The global `CustomElementRegistry` object associated with a {{domxref("Window")}} is not created using this constructor; it is automatically created when the window is set up, and is accessible via the {{domxref("window.customElements")}} property. The `CustomElementRegistry()` constructor is specifically for creating scoped registries that limit [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements) definitions to a particular scope.
+The constructor is specifically used for creating scoped registries that limit [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements) definitions to a particular scope, such as an element or {{domxref("ShadowRoot")}}.
+Note that the global `CustomElementRegistry` object associated with a {{domxref("Window")}} is not created using this constructor; it is automatically created when the window is set up, and is accessible via the {{domxref("window.customElements")}} property.

Conversation

pepelsbey commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Uh oh!

github-actions bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

hamishwillee Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hamishwillee Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

hamishwillee Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

hamishwillee left a comment

Choose a reason for hiding this comment

Uh oh!

pepelsbey commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hamishwillee Feb 22, 2026

Choose a reason for hiding this comment

Uh oh!

hamishwillee left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pepelsbey commented Feb 17, 2026 •

edited

Loading

github-actions bot commented Feb 17, 2026 •

edited

Loading

hamishwillee Feb 20, 2026 •

edited

Loading

pepelsbey commented Feb 20, 2026 •

edited

Loading