This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
The whenDefined() method of the CustomElementRegistry interface returns a Promise that resolves when the named element is defined.
whenDefined(name)
nameThe name of the custom element.
A Promise that fulfills with the custom element's constructor when a custom element becomes defined with the given name. If a custom element has already been defined with the name, the promise will immediately fulfill.
The promise is rejected with a SyntaxError DOMException if the name is not a valid custom element name.
This example uses whenDefined() to detect when the custom elements that make up a menu are defined. The menu displays placeholder content until the actual menu content is ready to display.
<nav id="menu-container">
<div class="menu-placeholder">Loading…</div>
<nav-menu>
<menu-item>Item 1</menu-item>
<menu-item>Item 2</menu-item>
…
<menu-item>Item N</menu-item>
</nav-menu>
</nav>
const container = document.getElementById("menu-container");
const placeholder = container.querySelector(".menu-placeholder");
// Fetch all the children of menu that are not yet defined.
const undefinedElements = container.querySelectorAll(":not(:defined)");
async function removePlaceholder() {
// Filter the elements down to unique localNames
const tags = new Set(
[...undefinedElements].map((button) => button.localName),
);
const promises = [...tags].map((tag) => customElements.whenDefined(tag));
// Wait for all the children to be upgraded
await Promise.all(promises);
// then remove the placeholder
container.removeChild(placeholder);
}
removePlaceholder();
| Specification |
|---|
| HTML> # dom-customelementregistry-whendefined-dev> |
| Desktop | Mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android | WebView on iOS | |
whenDefined |
54 | 79 | 63 | 41 | 10.1 | 54 | 63 | 41 | 10.3 | 6.0 | 54 | 10.3 |
© 2005–2025 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined