CustomElementRegistry: whenDefined() method
Baseline
Widely available
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.
Syntax
whenDefined(name)
Parameters
name-
The name of the custom element.
Return value
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.
Exceptions
SyntaxErrorDOMException-
The provided name is not a valid custom element name.
Examples
Basic usage
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();
Specifications
| Specification |
|---|
| HTML # dom-customelementregistry-whendefined-dev |
Browser compatibility
| desktop | mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
whenDefined
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Emoji and more Unicode in element and attribute names and namespace prefix (valid names match HTML parser)
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- No support
- No support