element-loaded

elementLoaded()

Detect when an element matching a selector is loaded into the DOM.

Synopsis

elementLoaded(selector)
    .then((element) => {
        // ...
    });

Syntax

elementLoaded(selector)
elementLoaded(selector, target)

Parameters

selector: A selector to match against.

target (Optional): An element to query and observe for matches. By default, this is the entire document.

Return Value

A Promise that is:

• Already fulfilled, if the selector matched an element already loaded into the document.
• Already rejected, if no match was found and the DOM has already finished loading.
• Asynchronously fulfilled, when a mutation occurs that adds an element matching the selector into the DOM.
• Asynchronously rejected, when the DOM has finished loading and a matching element has not been found.

Description

elementLoaded() will search the document with querySelector() against a given selector. If there is a match, then the returned promise will resolve immediately. If there is no match, but the document readyState is no longer loading, then the returned promise will reject immediately.

Otherwise, it will observe the document for matches using MutationObserver. If a matching mutation is observed, then the promise will resolve. By the time that the DOM has finished loading and the DOMContentLoaded event is fired, if no matching element has been found, then the promise will reject and the observer will disconnect.

Alternatives are:

• To simply handle an event for an element that does not exist yet, consider using event delegation.
• For more complicated cases, use MutationObserver directly.
• For building custom elements, consider Web Components.

See also:

• elementLoadedById()

Examples

See examples.