We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

CustomElementRegistry.whenDefined()

The whenDefined() method of the CustomElementRegistry interface returns a Promise that resolves when the named element is defined.

Syntax

Promise<> customElements.whenDefined(name);

Parameters

name
Custom element name.

Return value

A Promise that resolves to undefined when the custom element is defined. If the custom element is already defined, the promise is resolved immediately.

Exceptions

Exception Description
SyntaxError If the provided name is not a valid custom element name, the promise rejects with a SyntaxError.

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)');

const promises = [...undefinedElements].map(
  button => customElements.whenDefined(button.localName)
);

// Wait for all the children to be upgraded, 
// then remove the placeholder.
await Promise.all(promises);
container.removeChild(placeholder);

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'customElements.whenDefined()' in that specification.
Living Standard Initial definition.

Browser compatibility

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support

661

542

No3

594

Yes — 595

No

531

412

10.16
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support

661

542

661

542

No3

594

Yes — 595

531

412

10.166.02

1. Support for 'Customized built-in elements' as well.

2. Support for 'Autonomous custom elements' only.

3. Under consideration

4. From version 59: this feature is behind the dom.webcomponents.customelements.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

5. Until version 59 (exclusive): this feature is behind the dom.webcomponents.enabled preference (needs to be set to true) and the dom.webcomponents.customelements.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

6. Supports 'Autonomous custom elements' but not 'Customized built-in elements'

Document Tags and Contributors

Contributors to this page: jpmedley, fscholz, chrisdavidmills, Jedipedia, snuggs, arthurevans
Last updated by: jpmedley,