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.
The promise is rejected with a SyntaxError DOMException if the name is not a valid custom element name.
Examples
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 |