.load()


.load( url [, data ] [, complete ] )Returns: jQuery

Description: Load data from the server and place the returned HTML into the matched element.

Note: The event handling suite also has a method named .load(). jQuery determines which method to fire based on the set of arguments passed to it.

This method is the simplest way to fetch data from the server. It is roughly equivalent to $.get(url, data, success) except that it is a method rather than global function and it has an implicit callback function. When a successful response is detected (i.e. when textStatus is "success" or "notmodified"), .load() sets the HTML contents of the matched element to the returned data. This means that most uses of the method can be quite simple:

1
$( "#result" ).load( "ajax/test.html" );

If no element is matched by the selector — in this case, if the document does not contain an element with id="result" — the Ajax request will not be sent.

Callback Function

If a "complete" callback is provided, it is executed after post-processing and HTML insertion has been performed. The callback is fired once for each element in the jQuery collection, and this is set to each DOM element in turn.

1
2
3
$( "#result" ).load( "ajax/test.html", function() {
alert( "Load was performed." );
});

In the two examples above, if the current document does not contain an element with an ID of "result," the .load() method is not executed.

Request Method

The POST method is used if data is provided as an object; otherwise, GET is assumed.

Loading Page Fragments

The .load() method, unlike $.get(), allows us to specify a portion of the remote document to be inserted. This is achieved with a special syntax for the url parameter. If one or more space characters are included in the string, the portion of the string following the first space is assumed to be a jQuery selector that determines the content to be loaded.

We could modify the example above to use only part of the document that is fetched:

1
$( "#result" ).load( "ajax/test.html #container" );

When this method executes, it retrieves the content of ajax/test.html, but then jQuery parses the returned document to find the element with an ID of container. This element, along with its contents, is inserted into the element with an ID of result, and the rest of the retrieved document is discarded.

jQuery uses the browser's .innerHTML property to parse the retrieved document and insert it into the current document. During this process, browsers often filter elements from the document such as <html>, <title>, or <head> elements. As a result, the elements retrieved by .load() may not be exactly the same as if the document were retrieved directly by the browser.

Script Execution

When calling .load() using a URL without a suffixed selector expression, the content is passed to .html() prior to scripts being removed. This executes the script blocks before they are discarded. If .load() is called with a selector expression appended to the URL, however, the scripts are stripped out prior to the DOM being updated, and thus are not executed. An example of both cases can be seen below:

Here, any JavaScript loaded into #a as a part of the document will successfully execute.

1
$( "#a" ).load( "article.html" );

However, in the following case, script blocks in the document being loaded into #b are stripped out and not executed:

1
$( "#b" ).load( "article.html #target" );

Additional Notes:

  • Due to browser security restrictions, most "Ajax" requests are subject to the same origin policy; the request can not successfully retrieve data from a different domain, subdomain, port, or protocol.

Examples:

Example: Load another page's list items into an ordered list.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>load demo</title>
<style>
body {
font-size: 12px;
font-family: Arial;
}
</style>
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<b>Projects:</b>
<ol id="new-projects"></ol>
<script>
$( "#new-projects" ).load( "/resources/load.html #projects li" );
</script>
</body>
</html>

Demo:

Example: Display a notice if the Ajax request encounters an error.

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
28
29
30
31
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>load demo</title>
<style>
body {
font-size: 12px;
font-family: Arial;
}
</style>
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<b>Successful Response (should be blank):</b>
<div id="success"></div>
<b>Error Response:</b>
<div id="error"></div>
<script>
$( "#success" ).load( "/not-here.php", function( response, status, xhr ) {
if ( status == "error" ) {
var msg = "Sorry but there was an error: ";
$( "#error" ).html( msg + xhr.status + " " + xhr.statusText );
}
});
</script>
</body>
</html>

Demo:

Example: Load the feeds.html file into the div with the ID of feeds.

1
$( "#feeds" ).load( "feeds.html" );

Result:

1
<div id="feeds"><b>45</b> feeds found.</div>

Example: pass arrays of data to the server.

1
$( "#objectID" ).load( "test.php", { "choices[]": [ "Jon", "Susan" ] } );

Example: Same as above, but will POST the additional parameters to the server and a callback that is executed when the server is finished responding.

1
2
3
$( "#feeds" ).load( "feeds.php", { limit: 25 }, function() {
alert( "The last 25 entries in the feed have been loaded" );
});