Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Wait for an element to exist. ES6, Promise, MutationObserver
// MIT Licensed
// Author: jwilson8767
/**
* Waits for an element satisfying selector to exist, then resolves promise with the element.
* Useful for resolving race conditions.
*
* @param selector
* @returns {Promise}
*/
export function elementReady(selector) {
return new Promise((resolve, reject) => {
let el = document.querySelector(selector);
if (el) {
resolve(el);
return
}
new MutationObserver((mutationRecords, observer) => {
// Query for elements matching the specified selector
Array.from(document.querySelectorAll(selector)).forEach((element) => {
resolve(element);
//Once we have resolved we don't need the observer anymore.
observer.disconnect();
});
})
.observe(document.documentElement, {
childList: true,
subtree: true
});
});
}
import { elementReady } from "es6-element-ready";
// Simple usage to delete an element if/when it exists:
elementReady('#someWidget').then((someWidget)=>{someWidget.remove();});
@DavAlbert
Copy link

DavAlbert commented Nov 27, 2018

Oh great! I had big problems with that. Thank you very much

@quantuminformation
Copy link

quantuminformation commented Jan 10, 2019

Can you add to npm?

@quantuminformation
Copy link

quantuminformation commented Jan 10, 2019

also a timeout would be nice

@jwilson8767
Copy link
Author

jwilson8767 commented Aug 18, 2019

@quantuminformation, just saw your comments here.

No, I won't be adding this to NPM. I would however consider submitting it to any existing JS libraries that would benefit from having this if you know of one.

@spookyuser
Copy link

spookyuser commented Mar 9, 2020

This is really nice - thank you!

@jwilson8767
Copy link
Author

jwilson8767 commented Mar 9, 2020

You're welcome! I'm so glad someone is getting good use out of this!

@spookyuser
Copy link

spookyuser commented Mar 9, 2020

Yeah I really am getting good use out of it! This function is so much more readable than having MutationObserver all over. Plus it's super neat that the Promise resolves with the element you were looking for in the first place 🎉

@jwilson8767
Copy link
Author

jwilson8767 commented Mar 9, 2020

I really think this should be part of a standard kitchen sink library, but I have yet to find one that has evolved since the fall of jQuery / rise of ES6.

@spookyuser
Copy link

spookyuser commented Mar 11, 2020

100%

@danielpox
Copy link

danielpox commented Jul 8, 2020

Thanks a lot! This greatly improved the stability of a project of mine! Instead of waiting for x ms and then hoping it had appeared. Great work!

@jwilson8767
Copy link
Author

jwilson8767 commented Jul 10, 2020

@danielpox, glad it helped! Tweet it out for visibility, I keep hoping some kitchen sink library will want to adopt this.

@maximilianschmelzer
Copy link

maximilianschmelzer commented Aug 8, 2020

Very useful, thanks 🙂

@asontu
Copy link

asontu commented Dec 29, 2020

Inspired by this Gist I made my own function that takes more parameters to configure the MutationObserver and implements an optional Timeout that @quantuminformation asks about.

@jwilson8767
Copy link
Author

jwilson8767 commented Dec 30, 2020

@asontu, looks good! Glad you found this helpful!

@theimpostor
Copy link

theimpostor commented Feb 13, 2021

Thanks for the great sample! I found this very useful.

Question about this part:

...
document.querySelectorAll(selector)).forEach((element) => {
        resolve(element);
...

If selector matches multiple elements, why call resolve multiple times? Is there any benefit to doing that?

Seems to me you could just resolve on the first element, which means you could use the querySelector (not querySelectorAll), e.g.:

let element = document.querySelector(selector)
if (element) {
  resolve(element)
...

Just curious if there is some advantage to resolving multiple times.

@jwilson8767
Copy link
Author

jwilson8767 commented Feb 13, 2021

@theimposter, querySelectorAll always returns an array, which at the time that I wrote this seemed like a useful thing. However, as you point out, using querySelector is just fine too.

As to what happens if querySelectorAll suddenly matches multiple elements, the resolve() being called more than once does nothing after the first call. More recently, I've used RXJS Observables to actually make use of when more than one element is matched and re-combine or filter streams of events / changes in a more "functional" style (rather than handing around a ton of nested callbacks).

@JonahMoses
Copy link

JonahMoses commented May 4, 2021

what would this look like with using the querySelector vs querySelectorAll?

    new MutationObserver((mutationRecords, observer) => {
      Array.from(document.querySelectorAll(selector)).forEach((element) => {
        resolve(element);
        observer.disconnect();
      });
    }).observe(document.documentElement, {
      childList: true,
      subtree: true,
    });

@jwilson8767
Copy link
Author

jwilson8767 commented May 6, 2021

@JonahMoses, I believe it's as simple as this:

export function elementReady(selector) {
  return new Promise((resolve, reject) => {
    let el = document.querySelector(selector);
    if (el) {resolve(el);}
    new MutationObserver((mutationRecords, observer) => {
      // Query for element matching the specified selector
      const element = document.querySelector(selector);
      if (element) {
        resolve(element);
        //Once we have resolved we don't need the observer anymore.
        observer.disconnect();
      }
    })
      .observe(document.documentElement, {
        childList: true,
        subtree: true
      });
  });
}

@ivantacca
Copy link

ivantacca commented Oct 21, 2021

Hi, I have a question about that querySelector and querySelectorAll.
Assuming that we are looking for multiple elements to exist, this function will return only the first, but replacing the first querySelector with a querySelectorAll will return a nodeList immediately.

export function elementReady(selector) {
  return new Promise((resolve, reject) => {
    let el = document.querySelectorAll(selector);
    if (el) {resolve(el);}
    new MutationObserver((mutationRecords, observer) => {
      // Query for elements matching the specified selector
      Array.from(document.querySelectorAll(selector)).forEach((element) => {
        resolve(element);
        //Once we have resolved we don't need the observer anymore.
        observer.disconnect();
      });
    })
      .observe(document.documentElement, {
        childList: true,
        subtree: true
      });
  });
}

How would you implement this?

@jwilson8767
Copy link
Author

jwilson8767 commented Oct 21, 2021

@ivantacca What you're looking for is probably just to use the MutationObserver to give you all the matching elements, either once or perhaps periodically as the page changes. This is a bit different from what elementReady does, which is to give a single element as soon as it's added to the DOM. The first, and simplest way to wait for multiple elements to exist (when you know what their ids are) is to just call elementReady more than once and use Promise.all to wait for all them to exist:

Promise.all([elementReady('#element1'), elementReady('#element2'), elementReady('.element3')) ]).then(()=>{
//callback function body
})

The above only resolves once, so it's good for waiting during a page load where you know what elements need to load, and you don't need to repeat the callback function. For a more complicated case where you want to watch the entire page for new elements matching some selector, and periodically trigger a callback, I recommend the following approach:

/**
 * Watches for one or more elements matching a selector to exist, and calls the provided callback. Returns a function to stop the watcher.
 *
 * @param {string} selector
 * @param {function} callback
 * @param {boolean} once_per_element Set to true to only emit each element once. May leak memory for long-running pages with thousands of matched elements.
 * @returns {function} a function which stops the watcher when called.
 */
export function listenElements(selector, callback, once_per_element=false) {
  let known_elements = [];
  let _listenInnerTimeoutHandle = null;
  let _listenInner = () => {
    _listenInnerTimeoutHandle = null;
    const elements = Array.from(document.querySelectorAll(selector));
    if (elements.length) {
      if (once_per_element){
        const new_elements = elements.filter((el)=>!known_elements.includes(el))
        callback(new_elements)
        known_elements += new_elements;
      }else {
        callback(elements);
      }
    }
  }

  // immediately trigger inner function in case there are already matching elements
  _listenInnerTimeoutHandle = window.setTimeout(_listenInner, 0);

  const observer = new MutationObserver(() => {
    // skip mutations if inner is already scheduled (simple debouncing)
    if (_listenInnerTimeoutHandle) {
      return
    }
    // trigger inner function after a short delay for debouncing batches of mutations
    _listenInnerTimeoutHandle = window.setTimeout(_listenInner, 70);
  });
  observer.observe(document.documentElement, {
    childList: true,
    subtree: true
  });
  return () => {
    observer.disconnect()
  };
}

Sorry if that doesn't work out of the box, I didn't have time to test it fully.

If you want a more robust solution for dealing with this sort of thing, check out the "Observer" pattern and check out RXJS. Since I originally wrote elementReady.js I have switched a large portion of my projects over to using an RXJS as it lets me synchronize user interactions, state changes, and component render cycles without creating hugely jumbled code.

@acropup
Copy link

acropup commented Oct 22, 2021

Thanks for this nice little function. I noticed one fairly insubstantial bug, due to how calling a Promise's resolve() or reject() function doesn't act like a return statement. Code will continue executing, and in this case, a MutationObserver will be created even if the initial querySelector call was successful. The start of the promise should read like this, taking note of the return after the resolve:

let el = document.querySelector(selector);
if (el) { resolve(el); return; }

@jwilson8767
Copy link
Author

jwilson8767 commented Oct 27, 2021

@acropup Good point, fixed!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment