# webContents
> Render and control web pages.
Process: [Main](../glossary.md#main-process)
`webContents` is an [EventEmitter][event-emitter].
It is responsible for rendering and controlling a web page and is a property of
the [`BrowserWindow`](browser-window.md) object. An example of accessing the
`webContents` object:
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('http://github.com')
const contents = win.webContents
console.log(contents)
```
## Methods
These methods can be accessed from the `webContents` module:
```javascript
const { webContents } = require('electron')
console.log(webContents)
```
### `webContents.getAllWebContents()`
Returns `WebContents[]` - An array of all `WebContents` instances. This will contain web contents
for all windows, webviews, opened devtools, and devtools extension background pages.
### `webContents.getFocusedWebContents()`
Returns `WebContents` - The web contents that is focused in this application, otherwise
returns `null`.
### `webContents.fromId(id)`
* `id` Integer
Returns `WebContents` | undefined - A WebContents instance with the given ID, or
`undefined` if there is no WebContents associated with the given ID.
### `webContents.fromDevToolsTargetId(targetId)`
* `targetId` String - The Chrome DevTools Protocol [TargetID](https://chromedevtools.github.io/devtools-protocol/tot/Target/#type-TargetID) associated with the WebContents instance.
Returns `WebContents` | undefined - A WebContents instance with the given TargetID, or
`undefined` if there is no WebContents associated with the given TargetID.
When communicating with the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/),
it can be useful to lookup a WebContents instance based on its assigned TargetID.
```js
async function lookupTargetId (browserWindow) {
const wc = browserWindow.webContents
await wc.debugger.attach('1.3')
const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
const { targetId } = targetInfo
const targetWebContents = await webContents.fromDevToolsTargetId(targetId)
}
```
## Class: WebContents
> Render and control the contents of a BrowserWindow instance.
Process: [Main](../glossary.md#main-process)
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
### Instance Events
#### Event: 'did-finish-load'
Emitted when the navigation is done, i.e. the spinner of the tab has stopped
spinning, and the `onload` event was dispatched.
#### Event: 'did-fail-load'
Returns:
* `event` Event
* `errorCode` Integer
* `errorDescription` String
* `validatedURL` String
* `isMainFrame` Boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
This event is like `did-finish-load` but emitted when the load failed.
The full list of error codes and their meaning is available [here](https://source.chromium.org/chromium/chromium/src/+/master:net/base/net_error_list.h).
#### Event: 'did-fail-provisional-load'
Returns:
* `event` Event
* `errorCode` Integer
* `errorDescription` String
* `validatedURL` String
* `isMainFrame` Boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
This event is like `did-fail-load` but emitted when the load was cancelled
(e.g. `window.stop()` was invoked).
#### Event: 'did-frame-finish-load'
Returns:
* `event` Event
* `isMainFrame` Boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted when a frame has done navigation.
#### Event: 'did-start-loading'
Corresponds to the points in time when the spinner of the tab started spinning.
#### Event: 'did-stop-loading'
Corresponds to the points in time when the spinner of the tab stopped spinning.
#### Event: 'dom-ready'
Returns:
* `event` Event
Emitted when the document in the given frame is loaded.
#### Event: 'page-title-updated'
Returns:
* `event` Event
* `title` String
* `explicitSet` Boolean
Fired when page title is set during navigation. `explicitSet` is false when
title is synthesized from file url.
#### Event: 'page-favicon-updated'
Returns:
* `event` Event
* `favicons` String[] - Array of URLs.
Emitted when page receives favicon urls.
#### Event: 'new-window' _Deprecated_
Returns:
* `event` NewWindowWebContentsEvent
* `url` String
* `frameName` String
* `disposition` String - Can be `default`, `foreground-tab`, `background-tab`,
`new-window`, `save-to-disk` and `other`.
* `options` BrowserWindowConstructorOptions - The options which will be used for creating the new
[`BrowserWindow`](browser-window.md).
* `additionalFeatures` String[] - The non-standard features (features not handled
by Chromium or Electron) given to `window.open()`. Deprecated, and will now
always be the empty array `[]`.
* `referrer` [Referrer](structures/referrer.md) - The referrer that will be
passed to the new window. May or may not result in the `Referer` header being
sent, depending on the referrer policy.
* `postBody` [PostBody](structures/post-body.md) (optional) - The post data that
will be sent to the new window, along with the appropriate headers that will
be set. If no post data is to be sent, the value will be `null`. Only defined
when the window is being created by a form that set `target=_blank`.
Deprecated in favor of [`webContents.setWindowOpenHandler`](web-contents.md#contentssetwindowopenhandlerhandler).
Emitted when the page requests to open a new window for a `url`. It could be
requested by `window.open` or an external link like ``.
By default a new `BrowserWindow` will be created for the `url`.
Calling `event.preventDefault()` will prevent Electron from automatically creating a
new [`BrowserWindow`](browser-window.md). If you call `event.preventDefault()` and manually create a new
[`BrowserWindow`](browser-window.md) then you must set `event.newGuest` to reference the new [`BrowserWindow`](browser-window.md)
instance, failing to do so may result in unexpected behavior. For example:
```javascript
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {
event.preventDefault()
const win = new BrowserWindow({
webContents: options.webContents, // use existing webContents if provided
show: false
})
win.once('ready-to-show', () => win.show())
if (!options.webContents) {
const loadOptions = {
httpReferrer: referrer
}
if (postBody != null) {
const { data, contentType, boundary } = postBody
loadOptions.postData = postBody.data
loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`
}
win.loadURL(url, loadOptions) // existing webContents will be navigated automatically
}
event.newGuest = win
})
```
#### Event: 'did-create-window'
Returns:
* `window` BrowserWindow
* `details` Object
* `url` String - URL for the created window.
* `frameName` String - Name given to the created window in the
`window.open()` call.
* `options` BrowserWindowConstructorOptions - The options used to create the
BrowserWindow. They are merged in increasing precedence: parsed options
from the `features` string from `window.open()`, security-related
webPreferences inherited from the parent, and options given by
[`webContents.setWindowOpenHandler`](web-contents.md#contentssetwindowopenhandlerhandler).
Unrecognized options are not filtered out.
* `referrer` [Referrer](structures/referrer.md) - The referrer that will be
passed to the new window. May or may not result in the `Referer` header
being sent, depending on the referrer policy.
* `postBody` [PostBody](structures/post-body.md) (optional) - The post data
that will be sent to the new window, along with the appropriate headers
that will be set. If no post data is to be sent, the value will be `null`.
Only defined when the window is being created by a form that set
`target=_blank`.
* `disposition` String - Can be `default`, `foreground-tab`,
`background-tab`, `new-window`, `save-to-disk` and `other`.
Emitted _after_ successful creation of a window via `window.open` in the renderer.
Not emitted if the creation of the window is canceled from
[`webContents.setWindowOpenHandler`](web-contents.md#contentssetwindowopenhandlerhandler).
See [`window.open()`](window-open.md) for more details and how to use this in conjunction with `webContents.setWindowOpenHandler`.
#### Event: 'will-navigate'
Returns:
* `event` Event
* `url` String
Emitted when a user or the page wants to start navigation. It can happen when
the `window.location` object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with
APIs like `webContents.loadURL` and `webContents.back`.
It is also not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash`. Use `did-navigate-in-page` event for
this purpose.
Calling `event.preventDefault()` will prevent the navigation.
#### Event: 'did-start-navigation'
Returns:
* `event` Event
* `url` String
* `isInPlace` Boolean
* `isMainFrame` Boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted when any frame (including main) starts navigating. `isInPlace` will be
`true` for in-page navigations.
#### Event: 'will-redirect'
Returns:
* `event` Event
* `url` String
* `isInPlace` Boolean
* `isMainFrame` Boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted as a server side redirect occurs during navigation. For example a 302
redirect.
This event will be emitted after `did-start-navigation` and always before the
`did-redirect-navigation` event for the same navigation.
Calling `event.preventDefault()` will prevent the navigation (not just the
redirect).
#### Event: 'did-redirect-navigation'
Returns:
* `event` Event
* `url` String
* `isInPlace` Boolean
* `isMainFrame` Boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted after a server side redirect occurs during navigation. For example a 302
redirect.
This event cannot be prevented, if you want to prevent redirects you should
checkout out the `will-redirect` event above.
#### Event: 'did-navigate'
Returns:
* `event` Event
* `url` String
* `httpResponseCode` Integer - -1 for non HTTP navigations
* `httpStatusText` String - empty for non HTTP navigations
Emitted when a main frame navigation is done.
This event is not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash`. Use `did-navigate-in-page` event for
this purpose.
#### Event: 'did-frame-navigate'
Returns:
* `event` Event
* `url` String
* `httpResponseCode` Integer - -1 for non HTTP navigations
* `httpStatusText` String - empty for non HTTP navigations,
* `isMainFrame` Boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted when any frame navigation is done.
This event is not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash`. Use `did-navigate-in-page` event for
this purpose.
#### Event: 'did-navigate-in-page'
Returns:
* `event` Event
* `url` String
* `isMainFrame` Boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted when an in-page navigation happened in any frame.
When in-page navigation happens, the page URL changes but does not cause
navigation outside of the page. Examples of this occurring are when anchor links
are clicked or when the DOM `hashchange` event is triggered.
#### Event: 'will-prevent-unload'
Returns:
* `event` Event
Emitted when a `beforeunload` event handler is attempting to cancel a page unload.
Calling `event.preventDefault()` will ignore the `beforeunload` event handler
and allow the page to be unloaded.
```javascript
const { BrowserWindow, dialog } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('will-prevent-unload', (event) => {
const choice = dialog.showMessageBoxSync(win, {
type: 'question',
buttons: ['Leave', 'Stay'],
title: 'Do you want to leave this site?',
message: 'Changes you made may not be saved.',
defaultId: 0,
cancelId: 1
})
const leave = (choice === 0)
if (leave) {
event.preventDefault()
}
})
```
**Note:** This will be emitted for `BrowserViews` but will _not_ be respected - this is because we have chosen not to tie the `BrowserView` lifecycle to its owning BrowserWindow should one exist per the [specification](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event).
#### Event: 'crashed' _Deprecated_
Returns:
* `event` Event
* `killed` Boolean
Emitted when the renderer process crashes or is killed.
**Deprecated:** This event is superceded by the `render-process-gone` event
which contains more information about why the render process disappeared. It
isn't always because it crashed. The `killed` boolean can be replaced by
checking `reason === 'killed'` when you switch to that event.
#### Event: 'render-process-gone'
Returns:
* `event` Event
* `details` Object
* `reason` String - The reason the render process is gone. Possible values:
* `clean-exit` - Process exited with an exit code of zero
* `abnormal-exit` - Process exited with a non-zero exit code
* `killed` - Process was sent a SIGTERM or otherwise killed externally
* `crashed` - Process crashed
* `oom` - Process ran out of memory
* `launch-failed` - Process never successfully launched
* `integrity-failure` - Windows code integrity checks failed
* `exitCode` Integer - The exit code of the process, unless `reason` is
`launch-failed`, in which case `exitCode` will be a platform-specific
launch failure error code.
Emitted when the renderer process unexpectedly disappears. This is normally
because it was crashed or killed.
#### Event: 'unresponsive'
Emitted when the web page becomes unresponsive.
#### Event: 'responsive'
Emitted when the unresponsive web page becomes responsive again.
#### Event: 'plugin-crashed'
Returns:
* `event` Event
* `name` String
* `version` String
Emitted when a plugin process has crashed.
#### Event: 'destroyed'
Emitted when `webContents` is destroyed.
#### Event: 'before-input-event'
Returns:
* `event` Event
* `input` Object - Input properties.
* `type` String - Either `keyUp` or `keyDown`.
* `key` String - Equivalent to [KeyboardEvent.key][keyboardevent].
* `code` String - Equivalent to [KeyboardEvent.code][keyboardevent].
* `isAutoRepeat` Boolean - Equivalent to [KeyboardEvent.repeat][keyboardevent].
* `isComposing` Boolean - Equivalent to [KeyboardEvent.isComposing][keyboardevent].
* `shift` Boolean - Equivalent to [KeyboardEvent.shiftKey][keyboardevent].
* `control` Boolean - Equivalent to [KeyboardEvent.controlKey][keyboardevent].
* `alt` Boolean - Equivalent to [KeyboardEvent.altKey][keyboardevent].
* `meta` Boolean - Equivalent to [KeyboardEvent.metaKey][keyboardevent].
* `location` Number - Equivalent to [KeyboardEvent.location][keyboardevent].
* `modifiers` String[] - See [InputEvent.modifiers](structures/input-event.md).
Emitted before dispatching the `keydown` and `keyup` events in the page.
Calling `event.preventDefault` will prevent the page `keydown`/`keyup` events
and the menu shortcuts.
To only prevent the menu shortcuts, use
[`setIgnoreMenuShortcuts`](#contentssetignoremenushortcutsignore):
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('before-input-event', (event, input) => {
// For example, only enable application menu keyboard shortcuts when
// Ctrl/Cmd are down.
win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})
```
#### Event: 'enter-html-full-screen'
Emitted when the window enters a full-screen state triggered by HTML API.
#### Event: 'leave-html-full-screen'
Emitted when the window leaves a full-screen state triggered by HTML API.
#### Event: 'zoom-changed'
Returns:
* `event` Event
* `zoomDirection` String - Can be `in` or `out`.
Emitted when the user is requesting to change the zoom level using the mouse wheel.
#### Event: 'devtools-opened'
Emitted when DevTools is opened.
#### Event: 'devtools-closed'
Emitted when DevTools is closed.
#### Event: 'devtools-focused'
Emitted when DevTools is focused / opened.
#### Event: 'certificate-error'
Returns:
* `event` Event
* `url` String
* `error` String - The error code.
* `certificate` [Certificate](structures/certificate.md)
* `callback` Function
* `isTrusted` Boolean - Indicates whether the certificate can be considered trusted.
Emitted when failed to verify the `certificate` for `url`.
The usage is the same with [the `certificate-error` event of
`app`](app.md#event-certificate-error).
#### Event: 'select-client-certificate'
Returns:
* `event` Event
* `url` URL
* `certificateList` [Certificate[]](structures/certificate.md)
* `callback` Function
* `certificate` [Certificate](structures/certificate.md) - Must be a certificate from the given list.
Emitted when a client certificate is requested.
The usage is the same with [the `select-client-certificate` event of
`app`](app.md#event-select-client-certificate).
#### Event: 'login'
Returns:
* `event` Event
* `authenticationResponseDetails` Object
* `url` URL
* `authInfo` Object
* `isProxy` Boolean
* `scheme` String
* `host` String
* `port` Integer
* `realm` String
* `callback` Function
* `username` String (optional)
* `password` String (optional)
Emitted when `webContents` wants to do basic auth.
The usage is the same with [the `login` event of `app`](app.md#event-login).
#### Event: 'found-in-page'
Returns:
* `event` Event
* `result` Object
* `requestId` Integer
* `activeMatchOrdinal` Integer - Position of the active match.
* `matches` Integer - Number of Matches.
* `selectionArea` Rectangle - Coordinates of first match region.
* `finalUpdate` Boolean
Emitted when a result is available for
[`webContents.findInPage`] request.
#### Event: 'media-started-playing'
Emitted when media starts playing.
#### Event: 'media-paused'
Emitted when media is paused or done playing.
#### Event: 'did-change-theme-color'
Returns:
* `event` Event
* `color` (String | null) - Theme color is in format of '#rrggbb'. It is `null` when no theme color is set.
Emitted when a page's theme color changes. This is usually due to encountering
a meta tag:
```html
```
#### Event: 'update-target-url'
Returns:
* `event` Event
* `url` String
Emitted when mouse moves over a link or the keyboard moves the focus to a link.
#### Event: 'cursor-changed'
Returns:
* `event` Event
* `type` String
* `image` [NativeImage](native-image.md) (optional)
* `scale` Float (optional) - scaling factor for the custom cursor.
* `size` [Size](structures/size.md) (optional) - the size of the `image`.
* `hotspot` [Point](structures/point.md) (optional) - coordinates of the custom cursor's hotspot.
Emitted when the cursor's type changes. The `type` parameter can be `default`,
`crosshair`, `pointer`, `text`, `wait`, `help`, `e-resize`, `n-resize`,
`ne-resize`, `nw-resize`, `s-resize`, `se-resize`, `sw-resize`, `w-resize`,
`ns-resize`, `ew-resize`, `nesw-resize`, `nwse-resize`, `col-resize`,
`row-resize`, `m-panning`, `e-panning`, `n-panning`, `ne-panning`, `nw-panning`,
`s-panning`, `se-panning`, `sw-panning`, `w-panning`, `move`, `vertical-text`,
`cell`, `context-menu`, `alias`, `progress`, `nodrop`, `copy`, `none`,
`not-allowed`, `zoom-in`, `zoom-out`, `grab`, `grabbing` or `custom`.
If the `type` parameter is `custom`, the `image` parameter will hold the custom
cursor image in a [`NativeImage`](native-image.md), and `scale`, `size` and `hotspot` will hold
additional information about the custom cursor.
#### Event: 'context-menu'
Returns:
* `event` Event
* `params` Object
* `x` Integer - x coordinate.
* `y` Integer - y coordinate.
* `linkURL` String - URL of the link that encloses the node the context menu
was invoked on.
* `linkText` String - Text associated with the link. May be an empty
string if the contents of the link are an image.
* `pageURL` String - URL of the top level page that the context menu was
invoked on.
* `frameURL` String - URL of the subframe that the context menu was invoked
on.
* `srcURL` String - Source URL for the element that the context menu
was invoked on. Elements with source URLs are images, audio and video.
* `mediaType` String - Type of the node the context menu was invoked on. Can
be `none`, `image`, `audio`, `video`, `canvas`, `file` or `plugin`.
* `hasImageContents` Boolean - Whether the context menu was invoked on an image
which has non-empty contents.
* `isEditable` Boolean - Whether the context is editable.
* `selectionText` String - Text of the selection that the context menu was
invoked on.
* `titleText` String - Title text of the selection that the context menu was
invoked on.
* `altText` String - Alt text of the selection that the context menu was
invoked on.
* `suggestedFilename` String - Suggested filename to be used when saving file through 'Save
Link As' option of context menu.
* `selectionRect` [Rectangle](structures/rectangle.md) - Rect representing the coordinates in the document space of the selection.
* `selectionStartOffset` Number - Start position of the selection text.
* `referrerPolicy` [Referrer](structures/referrer.md) - The referrer policy of the frame on which the menu is invoked.
* `misspelledWord` String - The misspelled word under the cursor, if any.
* `dictionarySuggestions` String[] - An array of suggested words to show the
user to replace the `misspelledWord`. Only available if there is a misspelled
word and spellchecker is enabled.
* `frameCharset` String - The character encoding of the frame on which the
menu was invoked.
* `inputFieldType` String - If the context menu was invoked on an input
field, the type of that field. Possible values are `none`, `plainText`,
`password`, `other`.
* `spellcheckEnabled` Boolean - If the context is editable, whether or not spellchecking is enabled.
* `menuSourceType` String - Input source that invoked the context menu.
Can be `none`, `mouse`, `keyboard`, `touch`, `touchMenu`, `longPress`, `longTap`, `touchHandle`, `stylus`, `adjustSelection`, or `adjustSelectionReset`.
* `mediaFlags` Object - The flags for the media element the context menu was
invoked on.
* `inError` Boolean - Whether the media element has crashed.
* `isPaused` Boolean - Whether the media element is paused.
* `isMuted` Boolean - Whether the media element is muted.
* `hasAudio` Boolean - Whether the media element has audio.
* `isLooping` Boolean - Whether the media element is looping.
* `isControlsVisible` Boolean - Whether the media element's controls are
visible.
* `canToggleControls` Boolean - Whether the media element's controls are
toggleable.
* `canPrint` Boolean - Whether the media element can be printed.
* `canSave` Boolean - Whether or not the media element can be downloaded.
* `canShowPictureInPicture` Boolean - Whether the media element can show picture-in-picture.
* `isShowingPictureInPicture` Boolean - Whether the media element is currently showing picture-in-picture.
* `canRotate` Boolean - Whether the media element can be rotated.
* `canLoop` Boolean - Whether the media element can be looped.
* `editFlags` Object - These flags indicate whether the renderer believes it
is able to perform the corresponding action.
* `canUndo` Boolean - Whether the renderer believes it can undo.
* `canRedo` Boolean - Whether the renderer believes it can redo.
* `canCut` Boolean - Whether the renderer believes it can cut.
* `canCopy` Boolean - Whether the renderer believes it can copy.
* `canPaste` Boolean - Whether the renderer believes it can paste.
* `canDelete` Boolean - Whether the renderer believes it can delete.
* `canSelectAll` Boolean - Whether the renderer believes it can select all.
* `canEditRichly` Boolean - Whether the renderer believes it can edit text richly.
Emitted when there is a new context menu that needs to be handled.
#### Event: 'select-bluetooth-device'
Returns:
* `event` Event
* `devices` [BluetoothDevice[]](structures/bluetooth-device.md)
* `callback` Function
* `deviceId` String
Emitted when bluetooth device needs to be selected on call to
`navigator.bluetooth.requestDevice`. To use `navigator.bluetooth` api
`webBluetooth` should be enabled. If `event.preventDefault` is not called,
first available device will be selected. `callback` should be called with
`deviceId` to be selected, passing empty string to `callback` will
cancel the request.
```javascript
const { app, BrowserWindow } = require('electron')
let win = null
app.commandLine.appendSwitch('enable-experimental-web-platform-features')
app.whenReady().then(() => {
win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
event.preventDefault()
const result = deviceList.find((device) => {
return device.deviceName === 'test'
})
if (!result) {
callback('')
} else {
callback(result.deviceId)
}
})
})
```
#### Event: 'paint'
Returns:
* `event` Event
* `dirtyRect` [Rectangle](structures/rectangle.md)
* `image` [NativeImage](native-image.md) - The image data of the whole frame.
Emitted when a new frame is generated. Only the dirty area is passed in the
buffer.
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
// updateBitmap(dirty, image.getBitmap())
})
win.loadURL('http://github.com')
```
#### Event: 'devtools-reload-page'
Emitted when the devtools window instructs the webContents to reload
#### Event: 'will-attach-webview'
Returns:
* `event` Event
* `webPreferences` WebPreferences - The web preferences that will be used by the guest
page. This object can be modified to adjust the preferences for the guest
page.
* `params` Record - The other `` parameters such as the `src` URL.
This object can be modified to adjust the parameters of the guest page.
Emitted when a ``'s web contents is being attached to this web
contents. Calling `event.preventDefault()` will destroy the guest page.
This event can be used to configure `webPreferences` for the `webContents`
of a `` before it's loaded, and provides the ability to set settings
that can't be set via `` attributes.
**Note:** The specified `preload` script option will appear as `preloadURL`
(not `preload`) in the `webPreferences` object emitted with this event.
#### Event: 'did-attach-webview'
Returns:
* `event` Event
* `webContents` WebContents - The guest web contents that is used by the
``.
Emitted when a `` has been attached to this web contents.
#### Event: 'console-message'
Returns:
* `event` Event
* `level` Integer - The log level, from 0 to 3. In order it matches `verbose`, `info`, `warning` and `error`.
* `message` String - The actual console message
* `line` Integer - The line number of the source that triggered this console message
* `sourceId` String
Emitted when the associated window logs a console message.
#### Event: 'preload-error'
Returns:
* `event` Event
* `preloadPath` String
* `error` Error
Emitted when the preload script `preloadPath` throws an unhandled exception `error`.
#### Event: 'ipc-message'
Returns:
* `event` Event
* `channel` String
* `...args` any[]
Emitted when the renderer process sends an asynchronous message via `ipcRenderer.send()`.
#### Event: 'ipc-message-sync'
Returns:
* `event` Event
* `channel` String
* `...args` any[]
Emitted when the renderer process sends a synchronous message via `ipcRenderer.sendSync()`.
#### Event: 'desktop-capturer-get-sources'
Returns:
* `event` Event
Emitted when `desktopCapturer.getSources()` is called in the renderer process.
Calling `event.preventDefault()` will make it return empty sources.
#### Event: 'preferred-size-changed'
Returns:
* `event` Event
* `preferredSize` [Size](structures/size.md) - The minimum size needed to
contain the layout of the document—without requiring scrolling.
Emitted when the `WebContents` preferred size has changed.
This event will only be emitted when `enablePreferredSizeMode` is set to `true`
in `webPreferences`.
### Instance Methods
#### `contents.loadURL(url[, options])`
* `url` String
* `options` Object (optional)
* `httpReferrer` (String | [Referrer](structures/referrer.md)) (optional) - An HTTP Referrer url.
* `userAgent` String (optional) - A user agent originating the request.
* `extraHeaders` String (optional) - Extra headers separated by "\n".
* `postData` ([UploadRawData](structures/upload-raw-data.md) | [UploadFile](structures/upload-file.md))[] (optional)
* `baseURLForDataURL` String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified `url` is a data url and needs to load other files.
Returns `Promise` - the promise will resolve when the page has finished loading
(see [`did-finish-load`](web-contents.md#event-did-finish-load)), and rejects
if the page fails to load (see
[`did-fail-load`](web-contents.md#event-did-fail-load)). A noop rejection handler is already attached, which avoids unhandled rejection errors.
Loads the `url` in the window. The `url` must contain the protocol prefix,
e.g. the `http://` or `file://`. If the load should bypass http cache then
use the `pragma` header to achieve it.
```javascript
const { webContents } = require('electron')
const options = { extraHeaders: 'pragma: no-cache\n' }
webContents.loadURL('https://github.com', options)
```
#### `contents.loadFile(filePath[, options])`
* `filePath` String
* `options` Object (optional)
* `query` Record (optional) - Passed to `url.format()`.
* `search` String (optional) - Passed to `url.format()`.
* `hash` String (optional) - Passed to `url.format()`.
Returns `Promise` - the promise will resolve when the page has finished loading
(see [`did-finish-load`](web-contents.md#event-did-finish-load)), and rejects
if the page fails to load (see [`did-fail-load`](web-contents.md#event-did-fail-load)).
Loads the given file in the window, `filePath` should be a path to
an HTML file relative to the root of your application. For instance
an app structure like this:
```sh
| root
| - package.json
| - src
| - main.js
| - index.html
```
Would require code like this
```js
win.loadFile('src/index.html')
```
#### `contents.downloadURL(url)`
* `url` String
Initiates a download of the resource at `url` without navigating. The
`will-download` event of `session` will be triggered.
#### `contents.getURL()`
Returns `String` - The URL of the current web page.
```javascript
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com').then(() => {
const currentURL = win.webContents.getURL()
console.log(currentURL)
})
```
#### `contents.getTitle()`
Returns `String` - The title of the current web page.
#### `contents.isDestroyed()`
Returns `Boolean` - Whether the web page is destroyed.
#### `contents.focus()`
Focuses the web page.
#### `contents.isFocused()`
Returns `Boolean` - Whether the web page is focused.
#### `contents.isLoading()`
Returns `Boolean` - Whether web page is still loading resources.
#### `contents.isLoadingMainFrame()`
Returns `Boolean` - Whether the main frame (and not just iframes or frames within it) is
still loading.
#### `contents.isWaitingForResponse()`
Returns `Boolean` - Whether the web page is waiting for a first-response from the main
resource of the page.
#### `contents.stop()`
Stops any pending navigation.
#### `contents.reload()`
Reloads the current web page.
#### `contents.reloadIgnoringCache()`
Reloads current page and ignores cache.
#### `contents.canGoBack()`
Returns `Boolean` - Whether the browser can go back to previous web page.
#### `contents.canGoForward()`
Returns `Boolean` - Whether the browser can go forward to next web page.
#### `contents.canGoToOffset(offset)`
* `offset` Integer
Returns `Boolean` - Whether the web page can go to `offset`.
#### `contents.clearHistory()`
Clears the navigation history.
#### `contents.goBack()`
Makes the browser go back a web page.
#### `contents.goForward()`
Makes the browser go forward a web page.
#### `contents.goToIndex(index)`
* `index` Integer
Navigates browser to the specified absolute web page index.
#### `contents.goToOffset(offset)`
* `offset` Integer
Navigates to the specified offset from the "current entry".
#### `contents.isCrashed()`
Returns `Boolean` - Whether the renderer process has crashed.
#### `contents.forcefullyCrashRenderer()`
Forcefully terminates the renderer process that is currently hosting this
`webContents`. This will cause the `render-process-gone` event to be emitted
with the `reason=killed || reason=crashed`. Please note that some webContents share renderer
processes and therefore calling this method may also crash the host process
for other webContents as well.
Calling `reload()` immediately after calling this
method will force the reload to occur in a new process. This should be used
when this process is unstable or unusable, for instance in order to recover
from the `unresponsive` event.
```js
contents.on('unresponsive', async () => {
const { response } = await dialog.showMessageBox({
message: 'App X has become unresponsive',
title: 'Do you want to try forcefully reloading the app?',
buttons: ['OK', 'Cancel'],
cancelId: 1
})
if (response === 0) {
contents.forcefullyCrashRenderer()
contents.reload()
}
})
```
#### `contents.setUserAgent(userAgent)`
* `userAgent` String
Overrides the user agent for this web page.
#### `contents.getUserAgent()`
Returns `String` - The user agent for this web page.
#### `contents.insertCSS(css[, options])`
* `css` String
* `options` Object (optional)
* `cssOrigin` String (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.
Returns `Promise` - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via `contents.removeInsertedCSS(key)`.
Injects CSS into the current web page and returns a unique key for the inserted
stylesheet.
```js
contents.on('did-finish-load', () => {
contents.insertCSS('html, body { background-color: #f00; }')
})
```
#### `contents.removeInsertedCSS(key)`
* `key` String
Returns `Promise` - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified
by its key, which is returned from `contents.insertCSS(css)`.
```js
contents.on('did-finish-load', async () => {
const key = await contents.insertCSS('html, body { background-color: #f00; }')
contents.removeInsertedCSS(key)
})
```
#### `contents.executeJavaScript(code[, userGesture])`
* `code` String
* `userGesture` Boolean (optional) - Default is `false`.
Returns `Promise` - A promise that resolves with the result of the executed code
or is rejected if the result of the code is a rejected promise.
Evaluates `code` in page.
In the browser window some HTML APIs like `requestFullScreen` can only be
invoked by a gesture from the user. Setting `userGesture` to `true` will remove
this limitation.
Code execution will be suspended until web page stop loading.
```js
contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
.then((result) => {
console.log(result) // Will be the JSON object from the fetch call
})
```
#### `contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])`
* `worldId` Integer - The ID of the world to run the javascript in, `0` is the default world, `999` is the world used by Electron's `contextIsolation` feature. You can provide any integer here.
* `scripts` [WebSource[]](structures/web-source.md)
* `userGesture` Boolean (optional) - Default is `false`.
Returns `Promise` - A promise that resolves with the result of the executed code
or is rejected if the result of the code is a rejected promise.
Works like `executeJavaScript` but evaluates `scripts` in an isolated context.
#### `contents.setIgnoreMenuShortcuts(ignore)`
* `ignore` Boolean
Ignore application menu shortcuts while this web contents is focused.
#### `contents.setWindowOpenHandler(handler)`
* `handler` Function<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
* `details` Object
* `url` String - The _resolved_ version of the URL passed to `window.open()`. e.g. opening a window with `window.open('foo')` will yield something like `https://the-origin/the/current/path/foo`.
* `frameName` String - Name of the window provided in `window.open()`
* `features` String - Comma separated list of window features provided to `window.open()`.
* `disposition` String - Can be `default`, `foreground-tab`, `background-tab`,
`new-window`, `save-to-disk` or `other`.
* `referrer` [Referrer](structures/referrer.md) - The referrer that will be
passed to the new window. May or may not result in the `Referer` header being
sent, depending on the referrer policy.
* `postBody` [PostBody](structures/post-body.md) (optional) - The post data that
will be sent to the new window, along with the appropriate headers that will
be set. If no post data is to be sent, the value will be `null`. Only defined
when the window is being created by a form that set `target=_blank`.
Returns `{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}` - `deny` cancels the creation of the new
window. `allow` will allow the new window to be created. Specifying `overrideBrowserWindowOptions` allows customization of the created window.
Returning an unrecognized value such as a null, undefined, or an object
without a recognized 'action' value will result in a console error and have
the same effect as returning `{action: 'deny'}`.
Called before creating a window a new window is requested by the renderer, e.g.
by `window.open()`, a link with `target="_blank"`, shift+clicking on a link, or
submitting a form with `