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

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

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

removePlaceholder();

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
whenDefined
67
Support for 'Customized built-in elements' as well.
54
Support for 'Autonomous custom elements' only.
79
Support for 'Customized built-in elements' as well.
79
Support for 'Autonomous custom elements' only.
63
No
54
Support for 'Customized built-in elements' as well.
41
Support for 'Autonomous custom elements' only.
10.1
Supports 'Autonomous custom elements' but not 'Customized built-in elements'
67
Support for 'Customized built-in elements' as well.
54
Support for 'Autonomous custom elements' only.
67
Support for 'Customized built-in elements' as well.
54
Support for 'Autonomous custom elements' only.
63
48
Support for 'Customized built-in elements' as well.
41
Support for 'Autonomous custom elements' only.
10.3
Supports 'Autonomous custom elements' but not 'Customized built-in elements'
9.0
Support for 'Customized built-in elements' as well.
6.0
Support for 'Autonomous custom elements' only.

© 2005–2021 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