Document 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.
; ;
Document Promises has multi-implementer interest and tests, but is not yet a standard due to implementers not actually prioritizing it highly enough.
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.
; // CommonJS exampleconst contentLoaded = contentLoaded;
Developers may use the ponyfill as-is.
contentLoaded;
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.
// callback once the document is parsed (119 bytes minified/gzipped)! { /c/ && documentbody ? document | /* callback */ : document}
// callback once the document is content loaded (120 bytes minified/gzipped)! { /c/ && documentbody ? document | /* callback */ : document}
// callback once the document is fully loaded (112 bytes minified/gzipped)! { /m/ ? document | /* callback */ : document}
For convenience, each of these callback versions are available as modules.
; ;