What's the Difference Between jQuery's document.ready() and window.load()?

If you’ve used any jQuery plugins in your time – and lord knows I used to live on jQuery plugins – then you’ve probably seen the example code tell you to wrap your plugin calls in a $(document).ready() or $(window).load() but do you know what they are or how they’re different? Most people are very familiar with $(document).ready() but not a lot of love is given to $(window).load. If you’re trying to understand how jQuery works and move beyond the copy-paste mentality that many new JavaScript developers start off with, here’s a quick but thorough explanation of these functions and how to use them.

Say hello to $(document).ready()

The jQuery docs for $(document).ready() say it best:

A page can’t be manipulated safely until the document is “ready”.

But what does “ready” mean? In the context of the $(document).ready() function, “ready” means that the DOM (Document Object Model – the browser’s internal model of the markup on the page) is ready or fully constructed. Page rendering happens quickly to us but when it comes to code being executed on the page you always want to make sure that the DOM elements you are targeting with jQuery actually exist and are fully loaded (parents, children, and siblings). If you try to fire off a transition or a fade in/fade out on page load without wrapping it in a $(document).ready() you risk the code doing nothing because the element you’re trying to manipulate hasn’t rendered. Besides the fact that most JavaScript loaded in a page is blocking (stops page rendering until fully loaded), the problem that $(document).ready() solves is also one of the reasons that loading all JS after all of your HTML and before the closing <body> tag is a recommended best practice.

Pro tip: $(document).ready() shortcut

Have you ever seen code like this and wondered what it’s doing:

1
2
3
$(function() {
  $('div.welcome-message').fadeIn(2000);
});

Where’s the $(document).ready()? It’s actually right there. New jQuery developers aren’t familiar with this shorthand which is equivalent to wrapping a function in $(document).ready() like this code:

1
2
3
$(document).ready(function() {
  $('div.welcome-message').fadeIn(2000);
});

Wrapping your jQuery in $() has the same effect as $(document).ready().

Reintroducing $(window).load()

The $(window).load() function is similar to $(document).ready() but goes slightly further. Instead of waiting for just the DOM to be ready, $(window).load() won’t fire until the entire page has finished loading. This means stylesheets, images, and any resources that are referenced immediately but may not have completed downloading by the time the DOM is ready.

Use case

Image sliders are pretty much the most popular jQuery plugin type there is and it’s a perfect example of where $(window).load() comes in handy. Let’s say you have a series of images that will scroll in a slider automatically on page load. Let’s go further and say that you want the user to be able to take in and read and text contained in those images (text in images is bad form but there are some cases where it’s sort of acceptable) and/or viewing each image in order is important to understanding your page.

In a situation like the one described above the <img /> tags may be on the page and the DOM may be fully loaded and ready but you don’t want to fire off any scripts to start timing and moving those images in your slider until every image in the set is finished downloading. If you wrap your code in $(window).load() then you can fire off your slider safe in the knowledge that it won’t start sliding before all the images have loaded, potentially showing users blank or half loaded slides and making the images appear out of order and without context.

Conclusion

So there you have it. The difference between $(document).ready() (a.k.a. $()) and $(window).load() in practical terms. As always, when you write JavaScript make sure you’re use of jQuery is really necessary and that the same can’t be accomplished in a consistent way across browsers with Vanilla JS. In addition, all of your JavaScript should only be run when the DOM is ready. There’s really no use case where you wouldn’t care if the DOM was loaded or not and even if there was it would still be helpful (and good form) to check for DOM readiness.

If I missed something or you’ve thought of a reason why firing off JavaScript events before the DOM is ready could be perfectly valid, let me know in a comment.

Web development

« Terminal tricks that will change your life A better way to display the current year in your copyright notice »

Comments