view.webContents property
The view.webContents property is a read-only reference to the displayed WebContents object. Use this property to interact with the WebContents, such as to load a URL.
webcontents api
107 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
webContents.getAllWebContents() returns array of all WebContents instances
webContents.getAllWebContents() returns WebContents[] - an array of all WebContents instances. This includes web contents for all windows, webviews, opened DevTools, and DevTools extension background pages.
webContents.getFocusedWebContents() returns focused WebContents or null
webContents.getFocusedWebContents() returns WebContents | null - the web contents that is focused in the application, or null if none is focused.
webContents.fromId(id) retrieves WebContents by ID
webContents.fromId(id) takes an integer id and returns WebContents | undefined - a WebContents instance with the given ID, or undefined if no WebContents is associated with that ID.
webContents.fromFrame(frame) retrieves WebContents from WebFrameMain
webContents.fromFrame(frame) takes a WebFrameMain and returns WebContents | undefined - a WebContents instance associated with the given WebFrameMain, or undefined if none exists.
webContents.fromDevToolsTargetId(targetId) retrieves WebContents by Chrome DevTools Protocol TargetID
webContents.fromDevToolsTargetId(targetId) takes a string targetId (the Chrome DevTools Protocol TargetID) and returns WebContents | undefined. This is useful for looking up a WebContents instance based on its assigned TargetID when communicating with the Chrome DevTools Protocol.
did-finish-load event when navigation completes
The 'did-finish-load' event is emitted when navigation is done, meaning the spinner of the tab has stopped spinning and the onload event was dispatched.
did-fail-load event with error details
The 'did-fail-load' event is emitted when load failed. It returns: event Event, errorCode Integer, errorDescription string, validatedURL string, isMainFrame boolean, frameProcessId Integer, frameRoutingId Integer. The full list of error codes is available in Chromium's net_error_list.h.
did-fail-provisional-load event when load was cancelled
The 'did-fail-provisional-load' event is emitted when load was cancelled (e.g., window.stop() was invoked). It returns: event Event, errorCode Integer, errorDescription string, validatedURL string, isMainFrame boolean, frameProcessId Integer, frameRoutingId Integer.
did-frame-finish-load event when frame completes navigation
The 'did-frame-finish-load' event is emitted when a frame has done navigation. It returns: event Event, isMainFrame boolean, frameProcessId Integer, frameRoutingId Integer.
did-start-loading event corresponds to tab spinner starting
The 'did-start-loading' event corresponds to the points in time when the spinner of the tab started spinning.
did-stop-loading event corresponds to tab spinner stopping
The 'did-stop-loading' event corresponds to the points in time when the spinner of the tab stopped spinning.
dom-ready event when document loads
The 'dom-ready' event is emitted when the document in the top-level frame is loaded.
page-title-updated event with title and explicitSet flag
The 'page-title-updated' event is fired when page title is set during navigation. It returns: event Event, title string, explicitSet boolean. explicitSet is false when title is synthesized from file url.
page-favicon-updated event with favicon URLs
The 'page-favicon-updated' event is emitted when page receives favicon urls. It returns: event Event, favicons string[] (array of URLs).
content-bounds-updated event when page calls window.moveTo or window.resizeTo
The 'content-bounds-updated' event is emitted when the page calls window.moveTo, window.resizeTo or related APIs. It returns: event Event, bounds Rectangle. By default, this will move the window. Call event.preventDefault() to prevent that behavior.
did-create-window event after successful window.open() creation
The 'did-create-window' event is emitted after successful creation of a window via window.open in the renderer. It returns: window BrowserWindow, details Object. Not emitted if creation is canceled from webContents.setWindowOpenHandler. Details include: url string, frameName string, options BrowserWindowConstructorOptions, referrer Referrer, postBody PostBody (optional), disposition string (can be 'default', 'foreground-tab', 'background-tab', 'new-window', or 'other').
will-frame-navigate event fires before any frame navigation
The 'will-frame-navigate' event is emitted when a user or the page wants to start navigation in any frame (main frame or subframes). Unlike will-navigate, this fires for any frame. It will not emit for programmatic navigation or in-page navigations. Calling event.preventDefault() prevents the navigation. It returns: details Event with url string, isSameDocument boolean (always false for this event), isMainFrame boolean, frame WebFrameMain | null, initiator WebFrameMain | null (optional).
did-start-navigation event when any frame starts navigating
The 'did-start-navigation' event is emitted when any frame (including main) starts navigating. It returns: details Event with url string, isSameDocument boolean, isMainFrame boolean, frame WebFrameMain | null, initiator WebFrameMain | null (optional).
will-redirect event during server-side redirect navigation
The 'will-redirect' event is emitted when a server side redirect occurs during navigation (e.g., a 302 redirect). It is emitted after did-start-navigation and always before did-redirect-navigation. Calling event.preventDefault() prevents the navigation (not just the redirect). It returns: details Event with url string, isSameDocument boolean, isMainFrame boolean, frame WebFrameMain | null, initiator WebFrameMain | null (optional).
did-redirect-navigation event after server-side redirect
The 'did-redirect-navigation' event is emitted after a server side redirect occurs during navigation (e.g., a 302 redirect). This event cannot be prevented; use will-redirect to prevent redirects. It returns: details Event with url string, isSameDocument boolean, isMainFrame boolean, frame WebFrameMain | null, initiator WebFrameMain | null (optional).
did-frame-navigate event when any frame navigation completes
The 'did-frame-navigate' event is emitted when any frame navigation is done. It is not emitted for in-page navigations; use did-navigate-in-page for that. It 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.
did-navigate-in-page event for in-page navigation
The 'did-navigate-in-page' event is 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 the page. Examples are clicking anchor links or triggering the DOM hashchange event. It returns: event Event, url string, isMainFrame boolean, frameProcessId Integer, frameRoutingId Integer.
will-prevent-unload event when beforeunload handler tries to cancel unload
The 'will-prevent-unload' event is 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. This event will be emitted for BrowserViews but will not be respected due to BrowserView lifecycle design.
render-process-gone event when renderer process disappears
The 'render-process-gone' event is emitted when the renderer process unexpectedly disappears, normally because it was crashed or killed. It returns: event Event, details RenderProcessGoneDetails.
responsive event when unresponsive page becomes responsive
The 'responsive' event is emitted when the unresponsive web page becomes responsive again.
destroyed event when webContents is destroyed
The 'destroyed' event is emitted when webContents is destroyed.
input-event event when input event is sent to WebContents
The 'input-event' event is emitted when an input event is sent to the WebContents. It returns: event Event, inputEvent InputEvent.
before-input-event fires before keyboard events are dispatched
The 'before-input-event' event is emitted before dispatching keydown and keyup events in the page. Calling event.preventDefault() prevents the page keydown/keyup events and menu shortcuts. It returns: event Event, input Object with properties: type string (either 'keyUp' or 'keyDown'), key string (KeyboardEvent.key), code string (KeyboardEvent.code), isAutoRepeat boolean, isComposing boolean, shift boolean, control boolean, alt boolean, meta boolean, location number, modifiers string[].
before-mouse-event fires before mouse events are dispatched
The 'before-mouse-event' event is emitted before dispatching mouse events in the page. Calling event.preventDefault() prevents the page mouse events. It returns: event Event, mouse MouseInputEvent.
enter-html-full-screen event when window enters full-screen via HTML API
The 'enter-html-full-screen' event is emitted when the window enters a full-screen state triggered by HTML API.
leave-html-full-screen event when window leaves full-screen via HTML API
The 'leave-html-full-screen' event is emitted when the window leaves a full-screen state triggered by HTML API.
zoom-changed event when user requests zoom level change
The 'zoom-changed' event is emitted when the user is requesting to change the zoom level using the mouse wheel. It returns: event Event, zoomDirection string (can be 'in' or 'out').
blur event when WebContents loses focus
The 'blur' event is emitted when the WebContents loses focus.
focus event when WebContents gains focus
The 'focus' event is emitted when the WebContents gains focus. On macOS, focus means the WebContents is the first responder of window. The focus and blur events should only be used to detect focus changes between different WebContents and BrowserView in the same window.
devtools-open-url event when link clicked in DevTools
The 'devtools-open-url' event is emitted when a link is clicked in DevTools or 'Open in new tab' is selected for a link in its context menu. It returns: event Event, url string (URL of the link that was clicked or selected).
devtools-search-query event when text search used in DevTools
The 'devtools-search-query' event is emitted when 'Search' is selected for text in DevTools context menu. It returns: event Event, query string (text to query for).
devtools-opened event when DevTools is opened
The 'devtools-opened' event is emitted when DevTools is opened.
devtools-closed event when DevTools is closed
The 'devtools-closed' event is emitted when DevTools is closed.
devtools-focused event when DevTools is focused or opened
The 'devtools-focused' event is emitted when DevTools is focused or opened.
certificate-error event when certificate verification fails
The 'certificate-error' event is emitted when failed to verify the certificate for a URL. It returns: event Event, url string, error string (the error code), certificate Certificate, callback Function with isTrusted boolean parameter, isMainFrame boolean. Usage is the same as the certificate-error event of app.
select-client-certificate event when client certificate is requested
The 'select-client-certificate' event is emitted when a client certificate is requested. It returns: event Event, url URL, certificateList Certificate[], callback Function with certificate Certificate parameter (must be from the given list). Usage is the same as the select-client-certificate event of app.
login event for basic authentication
The 'login' event is emitted when webContents wants to do basic auth. It returns: event Event, authenticationResponseDetails Object (url URL, pid number, isRequestForNavigation boolean, firstAuthAttempt boolean, responseHeaders Record<string, string | string[]> optional), authInfo Object (isProxy boolean, scheme string, host string, port Integer, realm string), callback Function with username string (optional) and password string (optional) parameters. Usage is the same as the login event of app.
found-in-page event with search results
The 'found-in-page' event is emitted when a result is available for webContents.findInPage request. It returns: event Event, result Object (requestId Integer, activeMatchOrdinal Integer - position of active match, matches Integer - number of matches, selectionArea Rectangle - coordinates of first match region, finalUpdate boolean).
media-started-playing event when media starts playing
The 'media-started-playing' event is emitted when media starts playing.
media-paused event when media is paused or stops
The 'media-paused' event is emitted when media is paused or done playing.
audio-state-changed event when audio becomes audible or inaudible
The 'audio-state-changed' event is emitted when media becomes audible or inaudible. It returns: event Event with audible boolean - true if one or more frames or child webContents are emitting audio.
did-change-theme-color event when page theme color changes
The 'did-change-theme-color' event is emitted when a page's theme color changes, usually due to encountering a meta name='theme-color' tag. It returns: event Event, color (string | null) - theme color in format '#rrggbb', or null when no theme color is set.
update-target-url event when mouse moves over link
The 'update-target-url' event is emitted when mouse moves over a link or the keyboard moves the focus to a link. It returns: event Event, url string.
cursor-changed event when cursor type changes
The 'cursor-changed' event is emitted when the cursor's type changes. It returns: event Event, type string (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), image NativeImage (optional, for custom cursors), scale Float (optional), size Size (optional), hotspot Point (optional).
context-menu event with detailed context information
The 'context-menu' event is emitted when there is a new context menu to handle. It returns: event Event, params Object with extensive properties: x Integer, y Integer, frame WebFrameMain | null, linkURL string, linkText string, pageURL string, frameURL string, srcURL string, mediaType string (none, image, audio, video, canvas, file, or plugin), hasImageContents boolean, isEditable boolean, selectionText string, titleText string, altText string, suggestedFilename string, selectionRect Rectangle, selectionStartOffset number, referrerPolicy Referrer, misspelledWord string, dictionarySuggestions string[], frameCharset string, formControlType string, spellcheckEnabled boolean, menuSourceType string (none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, or adjustSelectionReset), mediaFlags Object, editFlags Object.
select-bluetooth-device event when Bluetooth device selection needed
The 'select-bluetooth-device' event is emitted when a bluetooth device needs to be selected for navigator.bluetooth.requestDevice call. It returns: event Event, devices BluetoothDevice[], callback Function with deviceId string parameter. Pass empty string to callback to cancel. If no listener is added, all bluetooth requests are cancelled. If event.preventDefault is not called, the first available device is automatically selected. May fire multiple times until callback is called.
paint event for offscreen rendering with frame image
The 'paint' event is emitted when a new frame is generated for offscreen rendering. It returns: details Event with texture OffscreenSharedTexture (optional, experimental, when webPreferences.offscreen.useSharedTexture is true), dirtyRect Rectangle, image NativeImage (image data of whole frame). Only the dirty area is passed in the buffer. When using shared texture, manage texture lifecycle by calling texture.release() when done.
devtools-reload-page event when DevTools instructs page reload
The 'devtools-reload-page' event is emitted when the DevTools window instructs the webContents to reload.
will-attach-webview event before webview is attached
The 'will-attach-webview' event is emitted when a <webview>'s web contents is being attached to this web contents. It returns: event Event, webPreferences WebPreferences (can be modified), params Record<string, string> (other webview parameters like src URL, can be modified). Calling event.preventDefault() will destroy the guest page. Used to configure webPreferences for the <webview> before it's loaded.
did-attach-webview event after webview is attached
The 'did-attach-webview' event is emitted when a <webview> has been attached to this web contents. It returns: event Event, webContents WebContents (the guest web contents used by the <webview>).
console-message event when window logs console message
The 'console-message' event is emitted when the associated window logs a console message. It returns: details Event with message string, level string (info, warning, error, or debug), lineNumber Integer, sourceId string (URL of log source), frame WebFrameMain.
preload-error event when preload script throws exception
The 'preload-error' event is emitted when the preload script throws an unhandled exception. It returns: event Event, preloadPath string, error Error.
ipc-message-sync event from sync ipcRenderer.sendSync()
The 'ipc-message-sync' event is emitted when the renderer process sends a synchronous message via ipcRenderer.sendSync(). It returns: event IpcMainEvent, channel string, ...args any[]. Also see webContents.ipc property which provides an IpcMain-like interface for this WebContents.
preferred-size-changed event when preferred size changes
The 'preferred-size-changed' event is emitted when the WebContents preferred size has changed. It returns: event Event, preferredSize Size (minimum size needed to contain layout without scrolling). Only emitted when enablePreferredSizeMode is true in webPreferences.