Render and control web pages.
Process: Main
webContents
is an EventEmitter.
It is responsible for rendering and controlling a web page and is a property of
the BrowserWindow
object. An example of accessing the
webContents
object:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('https://github.com')
const contents = win.webContents
console.log(contents)
Several events can be used to monitor navigations as they occur within a webContents
.
When a webContents
navigates to another page (as opposed to an in-page navigation), the following events will be fired.
did-start-navigation
will-frame-navigate
will-navigate
(only fired when main frame navigates)will-redirect
(only fired when a redirect happens during navigation)did-redirect-navigation
(only fired when a redirect happens during navigation)did-frame-navigate
did-navigate
(only fired when main frame navigates)
Subsequent events will not fire if event.preventDefault()
is called on any of the cancellable events.
In-page navigations don't cause the page to reload, but instead navigate to a location within the current page. These events are not cancellable. For an in-page navigations, the following events will fire in this order:
The will-navigate
and did-navigate
events only fire when the mainFrame navigates.
If you want to also observe navigations in <iframe>
s, use will-frame-navigate
and did-frame-navigate
events.
These methods can be accessed from the webContents
module:
const { webContents } = require('electron')
console.log(webContents)
Returns WebContents[]
- An array of all WebContents
instances. This will contain web contents
for all windows, webviews, opened devtools, and devtools extension background pages.
Returns WebContents | null
- The web contents that is focused in this application, otherwise
returns null
.
id
Integer
Returns WebContents | undefined
- A WebContents instance with the given ID, or
undefined
if there is no WebContents associated with the given ID.
frame
WebFrameMain
Returns WebContents | undefined
- A WebContents instance with the given WebFrameMain, or
undefined
if there is no WebContents associated with the given WebFrameMain.
targetId
string - The Chrome DevTools Protocol 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, it can be useful to lookup a WebContents instance based on its assigned TargetID.
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 wc.fromDevToolsTargetId(targetId)
}
Render and control the contents of a BrowserWindow instance.
Process: Main
This class is not exported from the 'electron'
module. It is only available as a return value of other methods in the Electron API.
Emitted when the navigation is done, i.e. the spinner of the tab has stopped
spinning, and the onload
event was dispatched.
Returns:
event
EventerrorCode
IntegererrorDescription
stringvalidatedURL
stringisMainFrame
booleanframeProcessId
IntegerframeRoutingId
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.
Returns:
event
EventerrorCode
IntegererrorDescription
stringvalidatedURL
stringisMainFrame
booleanframeProcessId
IntegerframeRoutingId
Integer
This event is like did-fail-load
but emitted when the load was cancelled
(e.g. window.stop()
was invoked).
Returns:
event
EventisMainFrame
booleanframeProcessId
IntegerframeRoutingId
Integer
Emitted when a frame has done navigation.
Corresponds to the points in time when the spinner of the tab started spinning.
Corresponds to the points in time when the spinner of the tab stopped spinning.
Emitted when the document in the top-level frame is loaded.
Returns:
event
Eventtitle
stringexplicitSet
boolean
Fired when page title is set during navigation. explicitSet
is false when
title is synthesized from file url.
Returns:
event
Eventfavicons
string[] - Array of URLs.
Emitted when page receives favicon urls.
Returns:
event
Eventbounds
Rectangle - requested new content bounds
Emitted when the page calls window.moveTo
, window.resizeTo
or related APIs.
By default, this will move the window. To prevent that behavior, call
event.preventDefault()
.
Returns:
window
BrowserWindowdetails
Objecturl
string - URL for the created window.frameName
string - Name given to the created window in thewindow.open()
call.options
BrowserWindowConstructorOptions - The options used to create the BrowserWindow. They are merged in increasing precedence: parsed options from thefeatures
string fromwindow.open()
, security-related webPreferences inherited from the parent, and options given bywebContents.setWindowOpenHandler
. Unrecognized options are not filtered out.referrer
Referrer - The referrer that will be passed to the new window. May or may not result in theReferer
header being sent, depending on the referrer policy.postBody
PostBody (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 benull
. Only defined when the window is being created by a form that settarget=_blank
.disposition
string - Can bedefault
,foreground-tab
,background-tab
,new-window
orother
.
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
.
See window.open()
for more details and how to use this in conjunction with webContents.setWindowOpenHandler
.
Returns:
details
Event<>url
string - The URL the frame is navigating to.isSameDocument
boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations. This property is always set tofalse
for this event.isMainFrame
boolean - True if the navigation is taking place in a main frame.frame
WebFrameMain | null - The frame to be navigated. May benull
if accessed after the frame has either navigated or been destroyed.initiator
WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
url
string DeprecatedisInPlace
boolean DeprecatedisMainFrame
boolean DeprecatedframeProcessId
Integer DeprecatedframeRoutingId
Integer Deprecated
Emitted when a user or the page wants to start navigation on the main frame. 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.
Returns:
details
Event<>url
string - The URL the frame is navigating to.isSameDocument
boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations. This property is always set tofalse
for this event.isMainFrame
boolean - True if the navigation is taking place in a main frame.frame
WebFrameMain | null - The frame to be navigated. May benull
if accessed after the frame has either navigated or been destroyed.initiator
WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
Emitted when a user or the page wants to start navigation in any frame. It can happen when
the window.location
object is changed or a user clicks a link in the page.
Unlike will-navigate
, will-frame-navigate
is fired when the main frame or any of its subframes attempts to navigate. When the navigation event comes from the main frame, isMainFrame
will be true
.
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.
Returns:
details
Event<>url
string - The URL the frame is navigating to.isSameDocument
boolean - Whether the navigation happened without changing document. Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation.isMainFrame
boolean - True if the navigation is taking place in a main frame.frame
WebFrameMain | null - The frame to be navigated. May benull
if accessed after the frame has either navigated or been destroyed.initiator
WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
url
string DeprecatedisInPlace
boolean DeprecatedisMainFrame
boolean DeprecatedframeProcessId
Integer DeprecatedframeRoutingId
Integer Deprecated
Emitted when any frame (including main) starts navigating.
Returns:
details
Event<>url
string - The URL the frame is navigating to.isSameDocument
boolean - Whether the navigation happened without changing document. Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation.isMainFrame
boolean - True if the navigation is taking place in a main frame.frame
WebFrameMain | null - The frame to be navigated. May benull
if accessed after the frame has either navigated or been destroyed.initiator
WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
url
string DeprecatedisInPlace
boolean DeprecatedisMainFrame
boolean DeprecatedframeProcessId
Integer DeprecatedframeRoutingId
Integer Deprecated
Emitted when 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).
Returns:
details
Event<>url
string - The URL the frame is navigating to.isSameDocument
boolean - Whether the navigation happened without changing document. Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation.isMainFrame
boolean - True if the navigation is taking place in a main frame.frame
WebFrameMain | null - The frame to be navigated. May benull
if accessed after the frame has either navigated or been destroyed.initiator
WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. viawindow.open
with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was emitted.
url
string DeprecatedisInPlace
boolean DeprecatedisMainFrame
boolean DeprecatedframeProcessId
Integer DeprecatedframeRoutingId
Integer Deprecated
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.
Returns:
event
Eventurl
stringhttpResponseCode
Integer - -1 for non HTTP navigationshttpStatusText
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.
Returns:
event
Eventurl
stringhttpResponseCode
Integer - -1 for non HTTP navigationshttpStatusText
string - empty for non HTTP navigations,isMainFrame
booleanframeProcessId
IntegerframeRoutingId
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.
Returns:
event
Eventurl
stringisMainFrame
booleanframeProcessId
IntegerframeRoutingId
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.
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.
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.
Returns:
event
Eventdetails
RenderProcessGoneDetails
Emitted when the renderer process unexpectedly disappears. This is normally because it was crashed or killed.
Emitted when the web page becomes unresponsive.
Emitted when the unresponsive web page becomes responsive again.
Returns:
event
Eventname
stringversion
string
Emitted when a plugin process has crashed.
Emitted when webContents
is destroyed.
Returns:
event
EventinputEvent
InputEvent
Emitted when an input event is sent to the WebContents. See InputEvent for details.
Returns:
event
Eventinput
Object - Input properties.type
string - EitherkeyUp
orkeyDown
.key
string - Equivalent to KeyboardEvent.key.code
string - Equivalent to KeyboardEvent.code.isAutoRepeat
boolean - Equivalent to KeyboardEvent.repeat.isComposing
boolean - Equivalent to KeyboardEvent.isComposing.shift
boolean - Equivalent to KeyboardEvent.shiftKey.control
boolean - Equivalent to KeyboardEvent.controlKey.alt
boolean - Equivalent to KeyboardEvent.altKey.meta
boolean - Equivalent to KeyboardEvent.metaKey.location
number - Equivalent to KeyboardEvent.location.modifiers
string[] - See InputEvent.modifiers.
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
:
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)
})
Emitted when the window enters a full-screen state triggered by HTML API.
Emitted when the window leaves a full-screen state triggered by HTML API.
Returns:
event
EventzoomDirection
string - Can bein
orout
.
Emitted when the user is requesting to change the zoom level using the mouse wheel.
Emitted when the WebContents
loses focus.
Emitted when the WebContents
gains focus.
Note that on macOS, having focus means the WebContents
is the first responder
of window, so switching focus between windows would not trigger the focus
and
blur
events of WebContents
, as the first responder of each window is not
changed.
The focus
and blur
events of WebContents
should only be used to detect
focus change between different WebContents
and BrowserView
in the same
window.
Returns:
event
Eventurl
string - URL of the link that was clicked or selected.
Emitted when a link is clicked in DevTools or 'Open in new tab' is selected for a link in its context menu.
Returns:
event
Eventquery
string - text to query for.
Emitted when 'Search' is selected for text in its context menu.
Emitted when DevTools is opened.
Emitted when DevTools is closed.
Emitted when DevTools is focused / opened.
Returns:
event
Eventurl
stringerror
string - The error code.certificate
Certificatecallback
FunctionisTrusted
boolean - Indicates whether the certificate can be considered trusted.
isMainFrame
boolean
Emitted when failed to verify the certificate
for url
.
The usage is the same with the certificate-error
event of app
.
Returns:
event
Eventurl
URLcertificateList
Certificate[]callback
Functioncertificate
Certificate - 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
.
Returns:
event
EventauthenticationResponseDetails
Objecturl
URL
authInfo
ObjectisProxy
booleanscheme
stringhost
stringport
Integerrealm
string
callback
Functionusername
string (optional)password
string (optional)
Emitted when webContents
wants to do basic auth.
The usage is the same with the login
event of app
.
Returns:
event
Eventresult
ObjectrequestId
IntegeractiveMatchOrdinal
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.
Emitted when media starts playing.
Emitted when media is paused or done playing.
Returns:
event
Event<>audible
boolean - True if one or more frames or childwebContents
are emitting audio.
Emitted when media becomes audible or inaudible.
Returns:
event
Eventcolor
(string | null) - Theme color is in format of '#rrggbb'. It isnull
when no theme color is set.
Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
<meta name='theme-color' content='#ff0000'>
Returns:
event
Eventurl
string
Emitted when mouse moves over a link or the keyboard moves the focus to a link.
Returns:
event
Eventtype
stringimage
NativeImage (optional)scale
Float (optional) - scaling factor for the custom cursor.size
Size (optional) - the size of theimage
.hotspot
Point (optional) - coordinates of the custom cursor's hotspot.
Emitted when the cursor's type changes. The type
parameter can be pointer
,
crosshair
, hand
, 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
, m-panning-vertical
,
m-panning-horizontal
, 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
, custom
, null
, drag-drop-none
, drag-drop-move
, drag-drop-copy
,
drag-drop-link
, ns-no-resize
, ew-no-resize
, nesw-no-resize
, nwse-no-resize
,
or default
.
If the type
parameter is custom
, the image
parameter will hold the custom
cursor image in a NativeImage
, and scale
, size
and hotspot
will hold
additional information about the custom cursor.
Returns:
event
Eventparams
Objectx
Integer - x coordinate.y
Integer - y coordinate.frame
WebFrameMain | null - Frame from which the context menu was invoked. May benull
if accessed after the frame has either navigated or been destroyed.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 benone
,image
,audio
,video
,canvas
,file
orplugin
.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 - Rect representing the coordinates in the document space of the selection.selectionStartOffset
number - Start position of the selection text.referrerPolicy
Referrer - 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 themisspelledWord
. 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.formControlType
string - The source that the context menu was invoked on. Possible values includenone
,button-button
,field-set
,input-button
,input-checkbox
,input-color
,input-date
,input-datetime-local
,input-email
,input-file
,input-hidden
,input-image
,input-month
,input-number
,input-password
,input-radio
,input-range
,input-reset
,input-search
,input-submit
,input-telephone
,input-text
,input-time
,input-url
,input-week
,output
,reset-button
,select-list
,select-list
,select-multiple
,select-one
,submit-button
, andtext-area
,spellcheckEnabled
boolean - If the context is editable, whether or not spellchecking is enabled.menuSourceType
string - Input source that invoked the context menu. Can benone
,mouse
,keyboard
,touch
,touchMenu
,longPress
,longTap
,touchHandle
,stylus
,adjustSelection
, oradjustSelectionReset
.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.
Returns:
event
Eventdevices
BluetoothDevice[]callback
FunctiondeviceId
string
Emitted when a bluetooth device needs to be selected when a call to
navigator.bluetooth.requestDevice
is made. callback
should be called with
the deviceId
of the device to be selected. Passing an empty string to
callback
will cancel the request.
If an event listener is not added for this event, or if event.preventDefault
is not called when handling this event, the first available device will be
automatically selected.
Due to the nature of bluetooth, scanning for devices when
navigator.bluetooth.requestDevice
is called may take time and will cause
select-bluetooth-device
to fire multiple times until callback
is called
with either a device id or an empty string to cancel the request.
const { app, BrowserWindow } = require('electron')
let win = null
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) {
// The device wasn't found so we need to either wait longer (eg until the
// device is turned on) or cancel the request by calling the callback
// with an empty string.
callback('')
} else {
callback(result.deviceId)
}
})
})
Returns:
details
Event<>texture
OffscreenSharedTexture (optional) Experimental - The GPU shared texture of the frame, whenwebPreferences.offscreen.useSharedTexture
istrue
.
dirtyRect
Rectangleimage
NativeImage - The image data of the whole frame.
Emitted when a new frame is generated. Only the dirty area is passed in the buffer.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
// updateBitmap(dirty, image.getBitmap())
})
win.loadURL('https://github.com')
When using shared texture (set webPreferences.offscreen.useSharedTexture
to true
) feature, you can pass the texture handle to external rendering pipeline without the overhead of
copying data between CPU and GPU memory, with Chromium's hardware acceleration support. This feature is helpful for high-performance rendering scenarios.
Only a limited number of textures can exist at the same time, so it's important that you call texture.release()
as soon as you're done with the texture.
By managing the texture lifecycle by yourself, you can safely pass the texture.textureInfo
to other processes through IPC.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ webPreferences: { offscreen: { useSharedTexture: true } } })
win.webContents.on('paint', async (e, dirty, image) => {
if (e.texture) {
// By managing lifecycle yourself, you can handle the event in async handler or pass the `e.texture.textureInfo`
// to other processes (not `e.texture`, the `e.texture.release` function is not passable through IPC).
await new Promise(resolve => setTimeout(resolve, 50))
// You can send the native texture handle to native code for importing into your rendering pipeline.
// For example: https://github.com/electron/electron/tree/main/spec/fixtures/native-addon/osr-gpu
// importTextureHandle(dirty, e.texture.textureInfo)
// You must call `e.texture.release()` as soon as possible, before the underlying frame pool is drained.
e.texture.release()
}
})
win.loadURL('https://github.com')
Emitted when the devtools window instructs the webContents to reload
Returns:
event
EventwebPreferences
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<string, string> - The other<webview>
parameters such as thesrc
URL. This object can be modified to adjust the parameters of the guest page.
Emitted when a <webview>
'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 <webview>
before it's loaded, and provides the ability to set settings
that can't be set via <webview>
attributes.
Returns:
event
EventwebContents
WebContents - The guest web contents that is used by the<webview>
.
Emitted when a <webview>
has been attached to this web contents.
Returns:
details
Event<>message
string - Message textlevel
string - Message severity Possible values includeinfo
,warning
,error
, anddebug
.lineNumber
Integer - Line number in the log sourcesourceId
string - URL of the log sourceframe
WebFrameMain - Frame that logged the message
level
Integer Deprecated - The log level, from 0 to 3. In order it matchesverbose
,info
,warning
anderror
.message
string Deprecated - The actual console messageline
Integer Deprecated - The line number of the source that triggered this console messagesourceId
string Deprecated
Emitted when the associated window logs a console message.
Returns:
event
EventpreloadPath
stringerror
Error
Emitted when the preload script preloadPath
throws an unhandled exception error
.
Returns:
event
IpcMainEventchannel
string...args
any[]
Emitted when the renderer process sends an asynchronous message via ipcRenderer.send()
.
See also webContents.ipc
, which provides an IpcMain
-like interface for responding to IPC messages specifically from this WebContents.
Returns:
event
IpcMainEventchannel
string...args
any[]
Emitted when the renderer process sends a synchronous message via ipcRenderer.sendSync()
.
See also webContents.ipc
, which provides an IpcMain
-like interface for responding to IPC messages specifically from this WebContents.
Returns:
event
EventpreferredSize
Size - 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
.
Returns:
event
Eventdetails
Objectframe
WebFrameMain | null - The created frame. May benull
if accessed after the frame has either navigated or been destroyed.
Emitted when the mainFrame, an <iframe>
, or a nested <iframe>
is loaded within the page.
url
stringoptions
Object (optional)httpReferrer
(string | Referrer) (optional) - An HTTP Referrer url.userAgent
string (optional) - A user agent originating the request.extraHeaders
string (optional) - Extra headers separated by "\n".postData
(UploadRawData | UploadFile)[] (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 specifiedurl
is a data url and needs to load other files.
Returns Promise<void>
- the promise will resolve when the page has finished loading
(see did-finish-load
), and rejects
if the page fails to load (see
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.
const win = new BrowserWindow()
const options = { extraHeaders: 'pragma: no-cache\n' }
win.webContents.loadURL('https://github.com', options)
filePath
stringoptions
Object (optional)query
Record<string, string> (optional) - Passed tourl.format()
.search
string (optional) - Passed tourl.format()
.hash
string (optional) - Passed tourl.format()
.
Returns Promise<void>
- the promise will resolve when the page has finished loading
(see did-finish-load
), and rejects
if the page fails to load (see 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:
| root
| - package.json
| - src
| - main.js
| - index.html
Would require code like this
const win = new BrowserWindow()
win.loadFile('src/index.html')
url
stringoptions
Object (optional)headers
Record<string, string> (optional) - HTTP request headers.
Initiates a download of the resource at url
without navigating. The
will-download
event of session
will be triggered.
Returns string
- The URL of the current web page.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com').then(() => {
const currentURL = win.webContents.getURL()
console.log(currentURL)
})
Returns string
- The title of the current web page.
Returns boolean
- Whether the web page is destroyed.
opts
Object (optional)waitForBeforeUnload
boolean - if true, fire thebeforeunload
event before closing the page. If the page prevents the unload, the WebContents will not be closed. Thewill-prevent-unload
will be fired if the page requests prevention of unload.
Closes the page, as if the web content had called window.close()
.
If the page is successfully closed (i.e. the unload is not prevented by the
page, or waitForBeforeUnload
is false or unspecified), the WebContents will
be destroyed and no longer usable. The destroyed
event
will be emitted.
Focuses the web page.
Returns boolean
- Whether the web page is focused.
Returns boolean
- Whether web page is still loading resources.
Returns boolean
- Whether the main frame (and not just iframes or frames within it) is
still loading.
Returns boolean
- Whether the web page is waiting for a first-response from the main
resource of the page.
Stops any pending navigation.
Reloads the current web page.
Reloads current page and ignores cache.
Returns boolean
- Whether the browser can go back to previous web page.
Deprecated: Should use the new contents.navigationHistory.canGoBack
API.
Returns boolean
- Whether the browser can go forward to next web page.
Deprecated: Should use the new contents.navigationHistory.canGoForward
API.
offset
Integer
Returns boolean
- Whether the web page can go to offset
.
Deprecated: Should use the new contents.navigationHistory.canGoToOffset
API.
Clears the navigation history.
Deprecated: Should use the new contents.navigationHistory.clear
API.
Makes the browser go back a web page.
Deprecated: Should use the new contents.navigationHistory.goBack
API.
Makes the browser go forward a web page.
Deprecated: Should use the new contents.navigationHistory.goForward
API.
index
Integer
Navigates browser to the specified absolute web page index.
Deprecated: Should use the new contents.navigationHistory.goToIndex
API.
offset
Integer
Navigates to the specified offset from the "current entry".
Deprecated: Should use the new contents.navigationHistory.goToOffset
API.
Returns boolean
- Whether the renderer process has crashed.
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.
const win = new BrowserWindow()
win.webContents.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) {
win.webContents.forcefullyCrashRenderer()
win.webContents.reload()
}
})
userAgent
string
Overrides the user agent for this web page.
Returns string
- The user agent for this web page.
css
stringoptions
Object (optional)cssOrigin
string (optional) - Can be 'user' or 'author'. Sets the cascade origin of the inserted stylesheet. Default is 'author'.
Returns Promise<string>
- 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.
const win = new BrowserWindow()
win.webContents.on('did-finish-load', () => {
win.webContents.insertCSS('html, body { background-color: #f00; }')
})
key
string
Returns Promise<void>
- 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)
.
const win = new BrowserWindow()
win.webContents.on('did-finish-load', async () => {
const key = await win.webContents.insertCSS('html, body { background-color: #f00; }')
win.webContents.removeInsertedCSS(key)
})
code
stringuserGesture
boolean (optional) - Default isfalse
.
Returns Promise<any>
- 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.
const win = new BrowserWindow()
win.webContents.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
})
worldId
Integer - The ID of the world to run the javascript in,0
is the default world,999
is the world used by Electron'scontextIsolation
feature. You can provide any integer here.scripts
WebSource[]userGesture
boolean (optional) - Default isfalse
.
Returns Promise<any>
- 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.
ignore
boolean
Ignore application menu shortcuts while this web contents is focused.
-
handler
Function<WindowOpenHandlerResponse>details
Objecturl
string - The resolved version of the URL passed towindow.open()
. e.g. opening a window withwindow.open('foo')
will yield something likehttps://the-origin/the/current/path/foo
.frameName
string - Name of the window provided inwindow.open()
features
string - Comma separated list of window features provided towindow.open()
.disposition
string - Can bedefault
,foreground-tab
,background-tab
,new-window
orother
.referrer
Referrer - The referrer that will be passed to the new window. May or may not result in theReferer
header being sent, depending on the referrer policy.postBody
PostBody (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 benull
. Only defined when the window is being created by a form that settarget=_blank
.
Returns
WindowOpenHandlerResponse
- When set to{ action: 'deny' }
cancels the creation of the new window.{ action: 'allow' }
will allow the new window to be created. 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 <form target="_blank">
. See
window.open()
for more details and how to use this in
conjunction with did-create-window
.
An example showing how to customize the process of new BrowserWindow
creation to be BrowserView
attached to main window instead:
const { BrowserView, BrowserWindow } = require('electron')
const mainWindow = new BrowserWindow()
mainWindow.webContents.setWindowOpenHandler((details) => {
return {
action: 'allow',
createWindow: (options) => {
const browserView = new BrowserView(options)
mainWindow.addBrowserView(browserView)
browserView.setBounds({ x: 0, y: 0, width: 640, height: 480 })
return browserView.webContents
}
}
})
muted
boolean
Mute the audio on the current web page.
Returns boolean
- Whether this page has been muted.
Returns boolean
- Whether audio is currently playing.
factor
Double - Zoom factor; default is 1.0.
Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
The factor must be greater than 0.0.
Returns number
- the current zoom factor.
level
number - Zoom level.
Changes the zoom level to the specified level. The original size is 0 and each
increment above or below represents zooming 20% larger or smaller to default
limits of 300% and 50% of original size, respectively. The formula for this is
scale := 1.2 ^ level
.
NOTE: The zoom policy at the Chromium level is same-origin, meaning that the zoom level for a specific domain propagates across all instances of windows with the same domain. Differentiating the window URLs will make zoom work per-window.
Returns number
- the current zoom level.
minimumLevel
numbermaximumLevel
number
Returns Promise<void>
Sets the maximum and minimum pinch-to-zoom level.
NOTE: Visual zoom is disabled by default in Electron. To re-enable it, call:
const win = new BrowserWindow() win.webContents.setVisualZoomLevelLimits(1, 3)
Executes the editing command undo
in web page.
Executes the editing command redo
in web page.
Executes the editing command cut
in web page.
Executes the editing command copy
in web page.
Centers the current text selection in web page.
x
Integery
Integer
Copy the image at the given position to the clipboard.
Executes the editing command paste
in web page.
Executes the editing command pasteAndMatchStyle
in web page.
Executes the editing command delete
in web page.
Executes the editing command selectAll
in web page.
Executes the editing command unselect
in web page.
Scrolls to the top of the current webContents
.
Scrolls to the bottom of the current webContents
.
options
Objectstart
Number (optional) - Amount to shift the start index of the current selection.end
Number (optional) - Amount to shift the end index of the current selection.
Adjusts the current text selection starting and ending points in the focused frame by the given amounts. A negative amount moves the selection towards the beginning of the document, and a positive amount moves the selection towards the end of the document.
Example:
const win = new BrowserWindow()
// Adjusts the beginning of the selection 1 letter forward,
// and the end of the selection 5 letters forward.
win.webContents.adjustSelection({ start: 1, end: 5 })
// Adjusts the beginning of the selection 2 letters forward,
// and the end of the selection 3 letters backward.
win.webContents.adjustSelection({ start: 2, end: -3 })
For a call of win.webContents.adjustSelection({ start: 1, end: 5 })
Before:
After:
text
string
Executes the editing command replace
in web page.
text
string
Executes the editing command replaceMisspelling
in web page.
text
string
Returns Promise<void>
Inserts text
to the focused element.
text
string - Content to be searched, must not be empty.options
Object (optional)forward
boolean (optional) - Whether to search forward or backward, defaults totrue
.findNext
boolean (optional) - Whether to begin a new text finding session with this request. Should betrue
for initial requests, andfalse
for follow-up requests. Defaults tofalse
.matchCase
boolean (optional) - Whether search should be case-sensitive, defaults tofalse
.
Returns Integer
- The request id used for the request.
Starts a request to find all matches for the text
in the web page. The result of the request
can be obtained by subscribing to found-in-page
event.
action
string - Specifies the action to take place when endingwebContents.findInPage
request.clearSelection
- Clear the selection.keepSelection
- Translate the selection into a normal selection.activateSelection
- Focus and click the selection node.
Stops any findInPage
request for the webContents
with the provided action
.
const win = new BrowserWindow()
win.webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) win.webContents.stopFindInPage('clearSelection')
})
const requestId = win.webContents.findInPage('api')
console.log(requestId)
rect
Rectangle (optional) - The area of the page to be captured.opts
Object (optional)stayHidden
boolean (optional) - Keep the page hidden instead of visible. Default isfalse
.stayAwake
boolean (optional) - Keep the system awake instead of allowing it to sleep. Default isfalse
.
Returns Promise<NativeImage>
- Resolves with a NativeImage
Captures a snapshot of the page within rect
. Omitting rect
will capture the whole visible page.
The page is considered visible when its browser window is hidden and the capturer count is non-zero.
If you would like the page to stay hidden, you should ensure that stayHidden
is set to true.
Returns boolean
- Whether this page is being captured. It returns true when the capturer count
is greater than 0.
Get the system printer list.
Returns Promise<PrinterInfo[]>
- Resolves with a PrinterInfo[]
options
Object (optional)silent
boolean (optional) - Don't ask user for print settings. Default isfalse
.printBackground
boolean (optional) - Prints the background color and image of the web page. Default isfalse
.deviceName
string (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.color
boolean (optional) - Set whether the printed web page will be in color or grayscale. Default istrue
.margins
Object (optional)marginType
string (optional) - Can bedefault
,none
,printableArea
, orcustom
. Ifcustom
is chosen, you will also need to specifytop
,bottom
,left
, andright
.top
number (optional) - The top margin of the printed web page, in pixels.bottom
number (optional) - The bottom margin of the printed web page, in pixels.left
number (optional) - The left margin of the printed web page, in pixels.right
number (optional) - The right margin of the printed web page, in pixels.
landscape
boolean (optional) - Whether the web page should be printed in landscape mode. Default isfalse
.scaleFactor
number (optional) - The scale factor of the web page.pagesPerSheet
number (optional) - The number of pages to print per page sheet.collate
boolean (optional) - Whether the web page should be collated.copies
number (optional) - The number of copies of the web page to print.pageRanges
Object[] (optional) - The page range to print. On macOS, only one range is honored.from
number - Index of the first page to print (0-based).to
number - Index of the last page to print (inclusive) (0-based).
duplexMode
string (optional) - Set the duplex mode of the printed web page. Can besimplex
,shortEdge
, orlongEdge
.dpi
Record<string, number> (optional)horizontal
number (optional) - The horizontal dpi.vertical
number (optional) - The vertical dpi.
header
string (optional) - string to be printed as page header.footer
string (optional) - string to be printed as page footer.pageSize
string | Size (optional) - Specify page size of the printed document. Can beA0
,A1
,A2
,A3
,A4
,A5
,A6
,Legal
,Letter
,Tabloid
or an Object containingheight
andwidth
.
callback
Function (optional)success
boolean - Indicates success of the print call.failureReason
string - Error description called back if the print fails.
When a custom pageSize
is passed, Chromium attempts to validate platform specific minimum values for width_microns
and height_microns
. Width and height must both be minimum 353 microns but may be higher on some operating systems.
Prints window's web page. When silent
is set to true
, Electron will pick
the system's default printer if deviceName
is empty and the default settings for printing.
Use page-break-before: always;
CSS style to force to print to a new page.
Example usage:
const win = new BrowserWindow()
const options = {
silent: true,
deviceName: 'My-Printer',
pageRanges: [{
from: 0,
to: 1
}]
}
win.webContents.print(options, (success, errorType) => {
if (!success) console.log(errorType)
})
options
Objectlandscape
boolean (optional) - Paper orientation.true
for landscape,false
for portrait. Defaults to false.displayHeaderFooter
boolean (optional) - Whether to display header and footer. Defaults to false.printBackground
boolean (optional) - Whether to print background graphics. Defaults to false.scale
number(optional) - Scale of the webpage rendering. Defaults to 1.pageSize
string | Size (optional) - Specify page size of the generated PDF. Can beA0
,A1
,A2
,A3
,A4
,A5
,A6
,Legal
,Letter
,Tabloid
,Ledger
, or an Object containingheight
andwidth
in inches. Defaults toLetter
.margins
Object (optional)top
number (optional) - Top margin in inches. Defaults to 1cm (~0.4 inches).bottom
number (optional) - Bottom margin in inches. Defaults to 1cm (~0.4 inches).left
number (optional) - Left margin in inches. Defaults to 1cm (~0.4 inches).right
number (optional) - Right margin in inches. Defaults to 1cm (~0.4 inches).
pageRanges
string (optional) - Page ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.headerTemplate
string (optional) - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:date
(formatted print date),title
(document title),url
(document location),pageNumber
(current page number) andtotalPages
(total pages in the document). For example,<span class=title></span>
would generate span containing the title.footerTemplate
string (optional) - HTML template for the print footer. Should use the same format as theheaderTemplate
.preferCSSPageSize
boolean (optional) - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size.generateTaggedPDF
boolean (optional) Experimental - Whether or not to generate a tagged (accessible) PDF. Defaults to false. As this property is experimental, the generated PDF may not adhere fully to PDF/UA and WCAG standards.generateDocumentOutline
boolean (optional) Experimental - Whether or not to generate a PDF document outline from content headers. Defaults to false.
Returns Promise<Buffer>
- Resolves with the generated PDF data.
Prints the window's web page as PDF.
The landscape
will be ignored if @page
CSS at-rule is used in the web page.
An example of webContents.printToPDF
:
const { app, BrowserWindow } = require('electron')
const fs = require('node:fs')
const path = require('node:path')
const os = require('node:os')
app.whenReady().then(() => {
const win = new BrowserWindow()
win.loadURL('https://github.com')
win.webContents.on('did-finish-load', () => {
// Use default printing options
const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
win.webContents.printToPDF({}).then(data => {
fs.writeFile(pdfPath, data, (error) => {
if (error) throw error
console.log(`Wrote PDF successfully to ${pdfPath}`)
})
}).catch(error => {
console.log(`Failed to write PDF to ${pdfPath}: `, error)
})
})
})
See Page.printToPdf for more information.
path
string
Adds the specified path to DevTools workspace. Must be used after DevTools creation:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
win.webContents.addWorkSpace(__dirname)
})
path
string
Removes the specified path from DevTools workspace.
devToolsWebContents
WebContents
Uses the devToolsWebContents
as the target WebContents
to show devtools.
The devToolsWebContents
must not have done any navigation, and it should not
be used for other purposes after the call.
By default Electron manages the devtools by creating an internal WebContents
with native view, which developers have very limited control of. With the
setDevToolsWebContents
method, developers can use any WebContents
to show
the devtools in it, including BrowserWindow
, BrowserView
and <webview>
tag.
Note that closing the devtools does not destroy the devToolsWebContents
, it
is caller's responsibility to destroy devToolsWebContents
.
An example of showing devtools in a <webview>
tag:
<html>
<head>
<style type="text/css">
* { margin: 0; }
#browser { height: 70%; }
#devtools { height: 30%; }
</style>
</head>
<body>
<webview id="browser" src="https://github.com"></webview>
<webview id="devtools" src="about:blank"></webview>
<script>
const { ipcRenderer } = require('electron')
const emittedOnce = (element, eventName) => new Promise(resolve => {
element.addEventListener(eventName, event => resolve(event), { once: true })
})
const browserView = document.getElementById('browser')
const devtoolsView = document.getElementById('devtools')
const browserReady = emittedOnce(browserView, 'dom-ready')
const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')
Promise.all([browserReady, devtoolsReady]).then(() => {
const targetId = browserView.getWebContentsId()
const devtoolsId = devtoolsView.getWebContentsId()
ipcRenderer.send('open-devtools', targetId, devtoolsId)
})
</script>
</body>
</html>
// Main process
const { ipcMain, webContents } = require('electron')
ipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {
const target = webContents.fromId(targetContentsId)
const devtools = webContents.fromId(devtoolsContentsId)
target.setDevToolsWebContents(devtools)
target.openDevTools()
})
An example of showing devtools in a BrowserWindow
:
const { app, BrowserWindow } = require('electron')
let win = null
let devtools = null
app.whenReady().then(() => {
win = new BrowserWindow()
devtools = new BrowserWindow()
win.loadURL('https://github.com')
win.webContents.setDevToolsWebContents(devtools.webContents)
win.webContents.openDevTools({ mode: 'detach' })
})
options
Object (optional)mode
string - Opens the devtools with specified dock state, can beleft
,right
,bottom
,undocked
,detach
. Defaults to last used dock state. Inundocked
mode it's possible to dock back. Indetach
mode it's not.activate
boolean (optional) - Whether to bring the opened devtools window to the foreground. The default istrue
.title
string (optional) - A title for the DevTools window (only inundocked
ordetach
mode).
Opens the devtools.
When contents
is a <webview>
tag, the mode
would be detach
by default,
explicitly passing an empty mode
can force using last used dock state.
On Windows, if Windows Control Overlay is enabled, Devtools will be opened with mode: 'detach'
.
Closes the devtools.
Returns boolean
- Whether the devtools is opened.
Returns boolean
- Whether the devtools view is focused .
Returns string
- the current title of the DevTools window. This will only be visible
if DevTools is opened in undocked
or detach
mode.
title
string
Changes the title of the DevTools window to title
. This will only be visible if DevTools is
opened in undocked
or detach
mode.
Toggles the developer tools.
x
Integery
Integer
Starts inspecting element at position (x
, y
).
Opens the developer tools for the shared worker context.
workerId
string
Inspects the shared worker based on its ID.
Returns SharedWorkerInfo[]
- Information about all Shared Workers.
Opens the developer tools for the service worker context.
channel
string...args
any[]
Send an asynchronous message to the renderer process via channel
, along with
arguments. Arguments will be serialized with the Structured Clone Algorithm,
just like postMessage
, so prototype chains will not be
included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will
throw an exception.
:::warning
Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
:::
For additional reading, refer to Electron's IPC guide.
frameId
Integer | [number, number] - the ID of the frame to send to, or a pair of[processId, frameId]
if the frame is in a different process to the main frame.channel
string...args
any[]
Send an asynchronous message to a specific frame in a renderer process via
channel
, along with arguments. Arguments will be serialized with the
Structured Clone Algorithm, just like postMessage
, so prototype
chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or
WeakSets will throw an exception.
NOTE: Sending non-standard JavaScript types such as DOM objects or special Electron objects will throw an exception.
The renderer process can handle the message by listening to channel
with the
ipcRenderer
module.
If you want to get the frameId
of a given renderer context you should use
the webFrame.routingId
value. E.g.
// In a renderer process
console.log('My frameId is:', require('electron').webFrame.routingId)
You can also read frameId
from all incoming IPC messages in the main process.
// In the main process
ipcMain.on('ping', (event) => {
console.info('Message came from frameId:', event.frameId)
})
channel
stringmessage
anytransfer
MessagePortMain[] (optional)
Send a message to the renderer process, optionally transferring ownership of
zero or more MessagePortMain
objects.
The transferred MessagePortMain
objects will be available in the renderer
process by accessing the ports
property of the emitted event. When they
arrive in the renderer, they will be native DOM MessagePort
objects.
For example:
// Main process
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
win.webContents.postMessage('port', { message: 'hello' }, [port1])
// Renderer process
ipcRenderer.on('port', (e, msg) => {
const [port] = e.ports
// ...
})
parameters
ObjectscreenPosition
string - Specify the screen type to emulate (default:desktop
):desktop
- Desktop screen type.mobile
- Mobile screen type.
screenSize
Size - Set the emulated screen size (screenPosition == mobile).viewPosition
Point - Position the view on the screen (screenPosition == mobile) (default:{ x: 0, y: 0 }
).deviceScaleFactor
Integer - Set the device scale factor (if zero defaults to original device scale factor) (default:0
).viewSize
Size - Set the emulated view size (empty means no override)scale
Float - Scale of emulated view inside available space (not in fit to view mode) (default:1
).
Enable device emulation with the given parameters.
Disable device emulation enabled by webContents.enableDeviceEmulation
.
inputEvent
MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent
Sends an input event
to the page.
Note: The BrowserWindow
containing the contents needs to be focused for
sendInputEvent()
to work.
onlyDirty
boolean (optional) - Defaults tofalse
.callback
Functionimage
NativeImagedirtyRect
Rectangle
Begin subscribing for presentation events and captured frames, the callback
will be called with callback(image, dirtyRect)
when there is a presentation
event.
The image
is an instance of NativeImage that stores the
captured frame.
The dirtyRect
is an object with x, y, width, height
properties that
describes which part of the page was repainted. If onlyDirty
is set to
true
, image
will only contain the repainted area. onlyDirty
defaults to
false
.
End subscribing for frame presentation events.
item
Objectfile
string - The path to the file being dragged.files
string[] (optional) - The paths to the files being dragged. (files
will overridefile
field)icon
NativeImage | string - The image must be non-empty on macOS.
Sets the item
as dragging item for current drag-drop operation, file
is the
absolute path of the file to be dragged, and icon
is the image showing under
the cursor when dragging.
fullPath
string - The absolute file path.saveType
string - Specify the save type.HTMLOnly
- Save only the HTML of the page.HTMLComplete
- Save complete-html page.MHTML
- Save complete-html page as MHTML.
Returns Promise<void>
- resolves if the page is saved.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.loadURL('https://github.com')
win.webContents.on('did-finish-load', async () => {
win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {
console.log('Page was saved successfully.')
}).catch(err => {
console.log(err)
})
})
Shows pop-up dictionary that searches the selected word on the page.
Returns boolean
- Indicates whether offscreen rendering is enabled.
If offscreen rendering is enabled and not painting, start painting.
If offscreen rendering is enabled and painting, stop painting.
Returns boolean
- If offscreen rendering is enabled returns whether it is currently painting.
fps
Integer
If offscreen rendering is enabled sets the frame rate to the specified number. Only values between 1 and 240 are accepted.
Returns Integer
- If offscreen rendering is enabled returns the current frame rate.
Schedules a full repaint of the window this web contents is in.
If offscreen rendering is enabled invalidates the frame and generates a new
one through the 'paint'
event.
Returns string
- Returns the WebRTC IP Handling Policy.
policy
string - Specify the WebRTC IP Handling Policy.default
- Exposes user's public and local IPs. This is the default behavior. When this policy is used, WebRTC has the right to enumerate all interfaces and bind them to discover public interfaces.default_public_interface_only
- Exposes user's public IP, but does not expose user's local IP. When this policy is used, WebRTC should only use the default route used by http. This doesn't expose any local addresses.default_public_and_private_interfaces
- Exposes user's public and local IPs. When this policy is used, WebRTC should only use the default route used by http. This also exposes the associated default private address. Default route is the route chosen by the OS on a multi-homed endpoint.disable_non_proxied_udp
- Does not expose public or local IPs. When this policy is used, WebRTC should only use TCP to contact peers or servers unless the proxy server supports UDP.
Setting the WebRTC IP handling policy allows you to control which IPs are exposed via WebRTC. See BrowserLeaks for more details.
Returns Object
:
min
Integer - The minimum UDP port number that WebRTC should use.max
Integer - The maximum UDP port number that WebRTC should use.
By default this value is { min: 0, max: 0 }
, which would apply no restriction on the udp port range.
udpPortRange
Objectmin
Integer - The minimum UDP port number that WebRTC should use.max
Integer - The maximum UDP port number that WebRTC should use.
Setting the WebRTC UDP Port Range allows you to restrict the udp port range used by WebRTC. By default the port range is unrestricted.
Note: To reset to an unrestricted port range this value should be set to { min: 0, max: 0 }
.
requestWebContents
WebContents - Web contents that the id will be registered to.
Returns string
- The identifier of a WebContents stream. This identifier can be used
with navigator.mediaDevices.getUserMedia
using a chromeMediaSource
of tab
.
The identifier is restricted to the web contents that it is registered to and is only valid for 10 seconds.
Returns Integer
- The operating system pid
of the associated renderer
process.
Returns Integer
- The Chromium internal pid
of the associated renderer. Can
be compared to the frameProcessId
passed by frame specific navigation events
(e.g. did-frame-navigate
)
filePath
string - Path to the output file.
Returns Promise<void>
- Indicates whether the snapshot has been created successfully.
Takes a V8 heap snapshot and saves it to filePath
.
Returns boolean
- whether or not this WebContents will throttle animations and timers
when the page becomes backgrounded. This also affects the Page Visibility API.
allowed
boolean
Controls whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.
Returns string
- the type of the webContent. Can be backgroundPage
, window
, browserView
, remote
, webview
or offscreen
.
policy
string - Can beanimate
,animateOnce
ornoAnimation
.
Sets the image animation policy for this webContents. The policy only affects
new images, existing images that are currently being animated are unaffected.
This is a known limitation in Chromium, you can force image animation to be
recalculated with img.src = img.src
which will result in no network traffic
but will update the animation policy.
This corresponds to the animationPolicy accessibility feature in Chromium.
An IpcMain
scoped to just IPC messages sent from this
WebContents.
IPC messages sent with ipcRenderer.send
, ipcRenderer.sendSync
or
ipcRenderer.postMessage
will be delivered in the following order:
contents.on('ipc-message')
contents.mainFrame.on(channel)
contents.ipc.on(channel)
ipcMain.on(channel)
Handlers registered with invoke
will be checked in the following order. The
first one that is defined will be called, the rest will be ignored.
contents.mainFrame.handle(channel)
contents.handle(channel)
ipcMain.handle(channel)
A handler or event listener registered on the WebContents will receive IPC
messages sent from any frame, including child frames. In most cases, only the
main frame can send IPC messages. However, if the nodeIntegrationInSubFrames
option is enabled, it is possible for child frames to send IPC messages also.
In that case, handlers should check the senderFrame
property of the IPC event
to ensure that the message is coming from the expected frame. Alternatively,
register handlers on the appropriate frame directly using the
WebFrameMain.ipc
interface.
A boolean
property that determines whether this page is muted.
A string
property that determines the user agent for this web page.
A number
property that determines the zoom level for this web contents.
The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is scale := 1.2 ^ level
.
A number
property that determines the zoom factor for this web contents.
The zoom factor is the zoom percent divided by 100, so 300% = 3.0.
An Integer
property that sets the frame rate of the web contents to the specified number.
Only values between 1 and 240 are accepted.
Only applicable if offscreen rendering is enabled.
A Integer
representing the unique ID of this WebContents. Each ID is unique among all WebContents
instances of the entire Electron application.
A Session
used by this webContents.
A NavigationHistory
used by this webContents.
A WebContents
instance that might own this WebContents
.
A WebContents | null
property that represents the of DevTools WebContents
associated with a given WebContents
.
Note: Users should never store this object because it may become null
when the DevTools has been closed.
A Debugger
instance for this webContents.
A boolean
property that determines whether or not this WebContents will throttle animations and timers
when the page becomes backgrounded. This also affects the Page Visibility API.
A WebFrameMain
property that represents the top frame of the page's frame hierarchy.
A WebFrameMain
property that represents the frame that opened this WebContents, either
with open(), or by navigating a link with a target attribute.