Skip to content

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 with NetworkError and code -1022. By default iOS doesn't allow apps to use unencrypted HTTP connections, and projects generated by the CLI don't lift this restriction. Use https://. http://localhost isn't subject to this restriction and can be used during development.

Return value ​

Promise<void>.

CaseResult
Loading finishesFulfills with undefined
The server returns 404, 500, and so onFulfills. 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 stringRejects 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-loadRejects with an error whose name is 'AbortError'
The page's process goes away mid-loadRejects
The page has been destroyedRejects with TypeError: Object has been destroyed

The rejection error has two extra fields:

  • code: the system's error code, the same as errorCode on did-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 ​

js
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 ​

js
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-load fires once at the same time, with errorCode -1003 and validatedURL https://no-such-host.invalid/.

Displaying an HTML string that references an image in the app bundle ​

js
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 ​