- url – the address to load the HTML snippet from (required).
- options – an [[mdn>Web/JavaScript/Reference/Global_Objects/Object|Object]] containing options for the HTTP request, as specified for the [[mdn>Web/API/Fetch_API|Fetch API]] (optional).
Returns:
A [[mdn>Web/JavaScript/Reference/Global_Objects/Promise|Promise]] object, as returned by the [[mdn>Web/API/fetch|fetch()]] global function.
Notes:
* This is an [[mdn>Learn/JavaScript/Asynchronous/Introducing|asynchronous]] function, as the fetched data may only be available after a delay.
* Security restrictions on which resources can be loaded, still apply to these requests. See [[mdn>Web/HTTP/CORS|CORS]] for more information.
* The loaded HTML snippet is inserted into the DOM “as is”, i.e. any header elements, etc. are also loaded. The recommended approach is to provide simple snippets without unnecessary elements.
* The loaded HTML snippets have to comply with [[mdn>Glossary/XHTML|XHTML]] rules (which are more strict than those for [[mdn>Glossary/HTML5|HTML5]]!)
* Among others, named entities (like “'' ''” and unclosed elements (e.g. “'' ''”) are not allowed within these files.
* It is however possible to have multiple root elements, as the snippet will be wrapped into a //temporary// root element before parsing. This element is then removed before inserting the file content.
* If the element that this is called on previously contained any child elements, these will be replaced by the loaded (X)HTML snippet.
===== Examples =====
A simple example could look like this:
document.getElementById('foo').load("bar.html");
Since this method returns a [[mdn>Web/JavaScript/Reference/Global_Objects/Promise|Promise]] object, the ''.then()'' method can be used to chain program code that is called only //after// the resource is loaded:
document.getElementById('foo')
.load("bar.html")
.then( result => {
console.info(result);
})
;
The [[mdn>Web/JavaScript/Reference/Global_Objects/Promise/then|.then()]]' method has an additional (optional) callback function, which gets called in case an error occurs:
document.getElementById('foo')
.load("bar.html")
.then(
success => {
console.info('success');
},
failure => {
console.error('failure');
}
)
;
A better approach to error handline, however, is to use the //Promise// object’s [[mdn>Web/JavaScript/Reference/Global_Objects/Promise/catch|.catch()]] and [[mdn>Web/JavaScript/Reference/Global_Objects/Promise/finally|.finally()]] methods instead. These work similar to standard JavaScript [[mdn>Web/JavaScript/Reference/Statements/try...catch|try … catch]] exception handling:
document.getElementById('foo')
.load("bar.html")
.then( … )
.catch( error => {
console.error(error);
})
.finally( () => {
console.info('done.');
})
;
===== See also =====
* [[toolbox:element:sethtml:index|.setHtml()]]
* [[toolbox:data:json-load:index|JSON.load()]]
===== More information =====
* [[mdn>Web/API/Fetch_API/Using_Fetch|Using Fetch]] on MDN.
* [[mdn>Web/JavaScript/Guide/Using_promises|Using promises]] on MDN.