WebContents: loadURL() method
The loadURL() method makes the web page load a URL. The returned Promise fulfills when loading finishes.
Syntax
loadURL(url)
loadURL(url, { baseURLForDataURL })Parameters
url
The URL to load, a string, which must include the scheme. https:, file:, data:, and about: are supported (about:blank is a blank page). A file: URL has the same effect as loadFile().
To display an HTML string, write it as a data: URL: 'data:text/html;charset=utf-8,' + encodeURIComponent(html).
options
An object. Optional. Passing null or undefined is the same as omitting it.
options.baseURLForDataURL
A string holding a full URL, such as 'https://example.com/docs/' or 'file://' + application.fileSystem.assets + '/web/'. It applies only to data: URLs: relative paths in the page (images, stylesheets, links) resolve against it, and the page's document.baseURI is set to it. A directory URL must end with /. It has no effect when url isn't a data: URL.
Note: Plain-text
http://URLs are blocked by the system: the Promise rejects withNetworkErrorandcode-1022. By default iOS doesn't allow apps to use unencrypted HTTP connections, and projects generated by the CLI don't lift this restriction. Usehttps://.http://localhostisn't subject to this restriction and can be used during development.
Return value
Promise<void>.
| Case | Result |
|---|---|
| Loading finishes | Fulfills with undefined |
| The server returns 404, 500, and so on | Fulfills. The error page finishes loading as usual. The status code is in httpResponseCode on the did-navigate event |
| The URL has no scheme, or is an empty string | Rejects with TypeError: loadURL: invalid URL; it must include the scheme, like https://. No load starts |
baseURLForDataURL isn't a full URL (such as 'docs/') | Rejects with TypeError: loadURL: baseURLForDataURL must be an absolute URL, like https://example.com/. No load starts |
| Network-level failure (domain can't be resolved, no network, timeout) | Rejects with an error whose name is 'NetworkError' |
Stopped by stop() | Rejects with an error whose name is 'AbortError' and code is -999 |
Superseded by another load (calling loadURL twice in a row) | The earlier one rejects with an error whose name is 'AbortError'; the later one fulfills as usual |
Destroyed by close() mid-load | Rejects with an error whose name is 'AbortError' |
| The page's process goes away mid-load | Rejects |
| The page has been destroyed | Rejects with TypeError: Object has been destroyed |
The rejection error has two extra fields:
code: the system's error code, the same aserrorCodeondid-fail-load.domain: where the error came from. Network-level errors are'NSURLErrorDomain'.
message is the description the system gives; its language follows the system, and it is only suitable for logging.
On failure, did-fail-load fires at the same time, carrying the same information as the rejection error. The exception: calling stop() right after loadURL rejects the Promise with AbortError but doesn't fire did-fail-load. To know the outcome of a loadURL call, rely on its Promise.
You can also ignore this Promise and only listen for events: a failure doesn't produce an extra unhandled rejection.
Exceptions
Doesn't throw directly. All errors reject the returned Promise.
Description
Reading isLoading() right after the call gives true. During loading, did-start-loading, did-navigate, did-stop-loading, and did-finish-load fire in that order.
A load the app starts with loadURL doesn't fire will-navigate.
With baseURLForDataURL, after loading getURL() returns baseURLForDataURL, not the data: URL (verified by testing). Without it, it returns the data: URL.
Examples
Waiting for loading to finish
const contents = new WebView().webContents;
await contents.loadURL('https://example.com/');
console.log('Loaded', contents.getURL());Result: It prints Loaded https://example.com/.
Handling load failures
const contents = new WebView().webContents;
try {
await contents.loadURL('https://no-such-host.invalid/');
} catch (err) {
const failure = /** @type {Error & { code: number }} */ (err);
console.log(failure.name, failure.code);
}Result
- It prints
NetworkError -1003. - The page stays on the previous page; it doesn't go blank and no error page is shown.
did-fail-loadfires once at the same time, witherrorCode-1003andvalidatedURLhttps://no-such-host.invalid/.
Displaying an HTML string that references an image in the app bundle
const contents = new WebView().webContents;
const html = '<!doctype html><title>Help</title><img src="sub/pic.png">';
await contents.loadURL('data:text/html;charset=utf-8,' + encodeURIComponent(html), {
baseURLForDataURL: 'file://' + application.fileSystem.assets + '/web/',
});
const width = await contents.executeJavaScript(
'new Promise((resolve) => { const i = document.images[0];' +
' if (i.complete) resolve(i.naturalWidth); else i.onload = () => resolve(i.naturalWidth); })');
console.log(width > 0);Result: When the project has assets/web/sub/pic.png, the image loads and it prints true. Not verified on a device.
Differences from Electron
Same as Electron's contents.loadURL(url, options). The second argument supports only baseURLForDataURL; httpReferrer, userAgent, extraHeaders, and postData aren't supported. The error codes are the system's set (-1003 and so on), not Chromium's (-105 and so on).
The native iOS equivalent is [webView loadRequest:]; a data: URL with baseURLForDataURL is [webView loadData:MIMEType:characterEncodingName:baseURL:], which is the general form of loadHTMLString:baseURL:.
See also
loadFile(): loading a local web page filedid-fail-load: what the error codes mean- Handling load failures