Document Promises

Document loading states as Promises

Document Promises is a ponyfill for document.parsed, document.contentLoaded, and document.loaded which allow you to run code after specific states of the document.

1fetch('data.json').then(function (data) {
2  document.parsed.then(function () {
3    document.querySelectorAll('.username').textContent = data.username;
4  });
5});

document.parsed

document.parsed is a promise that fulfills when the document is parsed and readyState is interactive, before deferred and async scripts have run.

document.contentLoaded

document.contentLoaded is a promise that fulfills when the document is parsed, blocking scripts have completed, and DOMContentLoaded fires.

document.loaded

document.loaded is a promise that fulfills when the document is parsed, blocking scripts have completed, images, scripts, links and sub-frames have finished loading, and readyState is complete.

Usage

Because Document Promises is a ponyfill, it does not attach parsed, contentLoaded or complete to the document by default. Instead, developers are encouraged to import the features individually.

1// ES6 example
2import { contentLoaded } from 'document-promises';
3
4// CommonJS example
5var contentLoaded = require('document-promises').contentLoaded;

Developers may use the ponyfill as-is.

1contentLoaded.then(function () {
2  /* document is ready */
3});

Developers are strongly advised not to attach these promises to document, as the standard may still change substantially, and then such code would be future-incompatible.

FAQ

What’s the difference between these promises and DOMContentLoaded?

One might easily miss an event like DOMContentLoaded if a script fires late, whereas a promise like contentLoaded guarantees the code will execute. Furthermore, using promises for state transitions is much more developer friendly.

What’s the browser support?

Document Promises works all major 2014+ browsers, including Chrome 33+, Edge 12+, Firefox 29+, Opera 20+, Safari 7+, iOS 8+, and Android 4.4.4 & 53+. With Promise and EventListener polyfilled, support goes back to all major 2001+ browsers, including Chrome 1+, Firefox 1+, Internet Explorer 5+, iOS 1+, Netscape Navigator 6+, Opera 7+, Safari 1+, and Android 1+.

What’s the catch?

Document Promises is public domain, dependency free, and 252 bytes or less when minified and gzipped.

Are there known limitations?

Yes, if this polyfill runs in a script that uses defer then contentLoaded will resolve before the DOMContentLoaded event.

Can this be done without a library?

Yes, if something needs to run once the document has reached a certain state, one of the following micro-optimized functions will suffice.

1// callback once the document is parsed (119 bytes minified/gzipped)
2!function d() {
3    /c/.test(document.readyState) && document.body
4    ? document.removeEventListener("readystatechange", d) | /* callback */
5    : document.addEventListener("readystatechange", d)
6}()

1// callback once the document is content loaded (120 bytes minified/gzipped)
2!function d() {
3    /c/.test(document.readyState) && document.body
4    ? document.removeEventListener("DOMContentLoaded", d) | /* callback */
5    : document.addEventListener("DOMContentLoaded", d)
6}()

1// callback once the document is fully loaded (112 bytes minified/gzipped)
2!function d() {
3    /m/.test(document.readyState)
4    ? document.removeEventListener("DOMContentLoaded", d) | /* callback */
5    : document.addEventListener("DOMContentLoaded", d)
6}()

For convenience, each of these callback versions are available as modules.

1import onParsed from 'document-promises/callback-versions/onParsed';
2
3onParsed(
4  () => {
5    // do something on parsed
6  }
7);