.ready()

Categories: Events > Document Loading

.ready( handler )Returns: jQuery

Description: Specify a function to execute when the DOM is fully loaded.

While JavaScript provides the load event for executing code when a page is rendered, this event does not get triggered until all assets such as images have been completely received. In most cases, the script can be run as soon as the DOM hierarchy has been fully constructed. The handler passed to .ready() is guaranteed to be executed after the DOM is ready, so this is usually the best place to attach all other event handlers and run other jQuery code. When using scripts that rely on the value of CSS style properties, it's important to reference external stylesheets or embed style elements before referencing the scripts.

In cases where code relies on loaded assets (for example, if the dimensions of an image are required), the code should be placed in a handler for the load event instead.

The .ready() method is generally incompatible with the <body onload=""> attribute. If load must be used, either do not use .ready() or use jQuery's .load() method to attach load event handlers to the window or to more specific items, like images.

All three of the following syntaxes are equivalent:

  • $( document ).ready( handler )
  • $().ready( handler ) (this is not recommended)
  • $( handler )

There is also $(document).on( "ready", handler ), deprecated as of jQuery 1.8. This behaves similarly to the ready method but if the ready event has already fired and you try to .on( "ready" ) the bound handler will not be executed. Ready handlers bound this way are executed after any bound by the other three methods above.

The .ready() method can only be called on a jQuery object matching the current document, so the selector can be omitted.

The .ready() method is typically used with an anonymous function:

1
2
3
 
$( document ).ready(function() {
  // Handler for .ready() called.
});

Which is equivalent to calling:

1
2
3
 
$(function() {
  // Handler for .ready() called.
});

If .ready() is called after the DOM has been initialized, the new handler passed in will be executed immediately.

Aliasing the jQuery Namespace

When using another JavaScript library, we may wish to call $.noConflict() to avoid namespace difficulties. When this function is called, the $ shortcut is no longer available, forcing us to write jQuery each time we would normally write $. However, the handler passed to the .ready() method can take an argument, which is passed the global jQuery object. This means we can rename the object within the context of our .ready() handler without affecting other code:

1
2
3
 
jQuery( document ).ready(function( $ ) {
  // Code using $ as usual goes here.
});

Example:

Display a message when the DOM is loaded.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>ready demo</title>
  <style>
  p {
    color: red;
  }
  </style>
  <script src="jquery-1.10.2.js"></script>
  <script>
 
  $( document ).ready(function() {
    $( "p" ).text( "The DOM is now loaded and can be manipulated." );
  });
 
  </script>
 
</head>
<body>
 
<p>Not loaded yet.</p>
 
 
</body>
</html>

Demo: