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


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


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.)


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


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>
    <menu-item>Item 1</menu-item>
    <menu-item>Item 2</menu-item>
    <menu-item>Item N</menu-item>
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);


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

Browser compatibility

BCD tables only load in the browser