Web/API/CustomElementRegistry/whenDefined

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

Syntax

customElements.whenDefined(name): Promise<CustomElementConstructor>;

Parameters

name: Custom element name.

Return value

A Promise that will be fulfilled with the custom element's constructor when a custom element becomes defined with the given name. (If such a custom element is already defined, the returned promise will be immediately fulfilled.)

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 StandardThe definition of 'customElements.whenDefined()' in that specification.	Living Standard	Initial definition.

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`whenDefined` Experimental'	Chrome Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Edge Full support 79 Notes' Full support 79 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 79 Notes' Notes' Support for 'Autonomous custom elements' only.	Firefox Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' 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.	IE No support No	Opera Full support 53 Notes' Full support 53 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 41 Notes' Notes' Support for 'Autonomous custom elements' only.	Safari Full support 10.1 Notes' Full support 10.1 Notes' Notes' Supports 'Autonomous custom elements' but not 'Customized built-in elements'	WebView Android Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Chrome Android Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Firefox Android Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' 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.	Opera Android Full support 47 Notes' Full support 47 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 41 Notes' Notes' Support for 'Autonomous custom elements' only.	Safari iOS Full support 10.3 Notes' Full support 10.3 Notes' Notes' Supports 'Autonomous custom elements' but not 'Customized built-in elements'	Samsung Internet Android Full support 9.0 Notes' Full support 9.0 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 6.0 Notes' Notes' Support for 'Autonomous custom elements' only.

Legend

Full support: Full support
No support: No support
Experimental. Expect behavior to change in the future.': Experimental. Expect behavior to change in the future.
See implementation notes.': See implementation notes.
User must explicitly enable this feature.': User must explicitly enable this feature.

CustomElementRegistry.whenDefined() by Mozilla Contributors is licensed under CC-BY-SA 2.5.