Category: Electron Api

Create and layout native views.

Process: Main

This module cannot be used until the ready event of the app module is emitted.

const { BaseWindow, View } = require('electron')
const win = new BaseWindow()
const view = new View()

view.setBackgroundColor('red')
view.setBounds({ x: 0, y: 0, width: 100, height: 100 })
win.contentView.addChildView(view)

Class: View​

A basic native view.

Process: Main

View is an EventEmitter.

new View()​

Creates a new View.

Instance Events​

Objects created with new View emit the following events:

Event: ‘bounds-changed’​

Emitted when the view’s bounds have changed in response to being laid out. The new bounds can be retrieved with view.getBounds().

Instance Methods​

Objects created with new View have the following instance methods:

view.addChildView(view[, index])​

• view View – Child view to add.
• index Integer (optional) – Index at which to insert the child view. Defaults to adding the child at the end of the child list.

If the same View is added to a parent which already contains it, it will be reordered such that it becomes the topmost view.

view.removeChildView(view)​

• view View – Child view to remove.

view.setBounds(bounds)​

• bounds Rectangle – New bounds of the View.

view.getBounds()​

Returns Rectangle – The bounds of this View, relative to its parent.

view.setBackgroundColor(color)​

• color string – Color in Hex, RGB, ARGB, HSL, HSLA or named CSS color format. The alpha channel is optional for the hex type.

Examples of valid color values:

• Hex
  • #fff (RGB)
  • #ffff (ARGB)
  • #ffffff (RRGGBB)
  • #ffffffff (AARRGGBB)
• RGB
  • rgb\(([\d]+),\s*([\d]+),\s*([\d]+)\)
    • e.g. rgb(255, 255, 255)
• RGBA
  • rgba\(([\d]+),\s*([\d]+),\s*([\d]+),\s*([\d.]+)\)
    • e.g. rgba(255, 255, 255, 1.0)
• HSL
  • hsl\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%\)
    • e.g. hsl(200, 20%, 50%)
• HSLA
  • hsla\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)
    • e.g. hsla(200, 20%, 50%, 0.5)
• Color name
  • Options are listed in SkParseColor.cpp
  • Similar to CSS Color Module Level 3 keywords, but case-sensitive.
    • e.g. blueviolet or red

Note: Hex format with alpha takes AARRGGBB or ARGB, not RRGGBBAA or RGB.

view.setVisible(visible)​

• visible boolean – If false, the view will be hidden from display.

Instance Properties​

Objects created with new View have the following properties:

view.children Readonly​

A View[] property representing the child views of this view.

Control web pages and iframes.

Process: Main

The webFrameMain module can be used to lookup frames across existing WebContents instances. Navigation events are the common use case.

const { BrowserWindow, webFrameMain } = require('electron')

const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('https://twitter.com')

win.webContents.on(
  'did-frame-navigate',
  (event, url, httpResponseCode, httpStatusText, isMainFrame, frameProcessId, frameRoutingId) => {
    const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)
    if (frame) {
      const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll("heck", "h*ck")'
      frame.executeJavaScript(code)
    }
  }
)

You can also access frames of existing pages by using the mainFrame property of WebContents.

const { BrowserWindow } = require('electron')

async function main () {
  const win = new BrowserWindow({ width: 800, height: 600 })
  await win.loadURL('https://reddit.com')

  const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {
    try {
      const url = new URL(frame.url)
      return url.host === 'www.youtube.com'
    } catch {
      return false
    }
  })

  console.log(youtubeEmbeds)
}

main()

Methods​

These methods can be accessed from the webFrameMain module:

webFrameMain.fromId(processId, routingId)​

• processId Integer – An Integer representing the internal ID of the process which owns the frame.
• routingId Integer – An Integer representing the unique frame ID in the current renderer process. Routing IDs can be retrieved from WebFrameMain instances (frame.routingId) and are also passed by frame specific WebContents navigation events (e.g. did-frame-navigate).

Returns WebFrameMain | undefined – A frame with the given process and routing IDs, or undefined if there is no WebFrameMain associated with the given IDs.

Class: WebFrameMain​

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.

Instance Events​

Event: ‘dom-ready’​

Emitted when the document is loaded.

Instance Methods​

frame.executeJavaScript(code[, userGesture])​

• code string
• userGesture boolean (optional) – Default is false.

Returns Promise<unknown> – A promise that resolves with the result of the executed code or is rejected if execution throws or results in 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.

frame.reload()​

Returns boolean – Whether the reload was initiated successfully. Only results in false when the frame has no history.

frame.send(channel, ...args)​

• 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.

The renderer process can handle the message by listening to channel with the ipcRenderer module.

frame.postMessage(channel, message, [transfer])​

• channel string
• message any
• transfer 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.mainFrame.postMessage('port', { message: 'hello' }, [port1])

// Renderer process
ipcRenderer.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

Instance Properties​

frame.ipc Readonly​

An IpcMain instance scoped to the frame.

IPC messages sent with ipcRenderer.send, ipcRenderer.sendSync or ipcRenderer.postMessage will be delivered in the following order:

1. contents.on('ipc-message')
2. contents.mainFrame.on(channel)
3. contents.ipc.on(channel)
4. 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.

1. contents.mainFrame.handle(channel)
2. contents.handle(channel)
3. ipcMain.handle(channel)

In most cases, only the main frame of a WebContents can send or receive IPC messages. However, if the nodeIntegrationInSubFrames option is enabled, it is possible for child frames to send and receive IPC messages also. The WebContents.ipc interface may be more convenient when nodeIntegrationInSubFrames is not enabled.

frame.url Readonly​

A string representing the current URL of the frame.

frame.origin Readonly​

A string representing the current origin of the frame, serialized according to RFC 6454. This may be different from the URL. For instance, if the frame is a child window opened to about:blank, then frame.origin will return the parent frame’s origin, while frame.url will return the empty string. Pages without a scheme/host/port triple origin will have the serialized origin of "null" (that is, the string containing the letters n, u, l, l).

frame.top Readonly​

A WebFrameMain | null representing top frame in the frame hierarchy to which frame belongs.

frame.parent Readonly​

A WebFrameMain | null representing parent frame of frame, the property would be null if frame is the top frame in the frame hierarchy.

frame.frames Readonly​

A WebFrameMain[] collection containing the direct descendents of frame.

frame.framesInSubtree Readonly​

A WebFrameMain[] collection containing every frame in the subtree of frame, including itself. This can be useful when traversing through all frames.

frame.frameTreeNodeId Readonly​

An Integer representing the id of the frame’s internal FrameTreeNode instance. This id is browser-global and uniquely identifies a frame that hosts content. The identifier is fixed at the creation of the frame and stays constant for the lifetime of the frame. When the frame is removed, the id is not used again.

frame.name Readonly​

A string representing the frame name.

frame.osProcessId Readonly​

An Integer representing the operating system pid of the process which owns this frame.

frame.processId Readonly​

An Integer representing the Chromium internal pid of the process which owns this frame. This is not the same as the OS process ID; to read that use frame.osProcessId.

frame.routingId Readonly​

An Integer representing the unique frame id in the current renderer process. Distinct WebFrameMain instances that refer to the same underlying frame will have the same routingId.

frame.visibilityState Readonly​

A string representing the visibility state of the frame.

See also how the Page Visibility API is affected by other Electron APIs.

A View that displays a WebContents.

Process: Main

This module cannot be used until the ready event of the app module is emitted.

const { BaseWindow, WebContentsView } = require('electron')
const win = new BaseWindow({ width: 800, height: 400 })

const view1 = new WebContentsView()
win.contentView.addChildView(view1)
view1.webContents.loadURL('https://electronjs.org')
view1.setBounds({ x: 0, y: 0, width: 400, height: 400 })

const view2 = new WebContentsView()
win.contentView.addChildView(view2)
view2.webContents.loadURL('https://github.com/electron/electron')
view2.setBounds({ x: 400, y: 0, width: 400, height: 400 })

Class: WebContentsView extends View​

A View that displays a WebContents.

Process: Main

WebContentsView inherits from View.

WebContentsView is an EventEmitter.

new WebContentsView([options])​

• options Object (optional)
  • webPreferences WebPreferences (optional) – Settings of web page’s features.
  • webContents WebContents (optional) – If present, the given WebContents will be adopted by the WebContentsView. A WebContents may only be presented in one WebContentsView at a time.

Creates a WebContentsView.

Instance Properties​

Objects created with new WebContentsView have the following properties, in addition to those inherited from View:

view.webContents Readonly​

A WebContents property containing a reference to the displayed WebContents. Use this to interact with the WebContents, for instance to load a URL.

const { WebContentsView } = require('electron')
const view = new WebContentsView()
view.webContents.loadURL('https://electronjs.org/')

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)

Navigation Events​

Several events can be used to monitor navigations as they occur within a webContents.

Document Navigations​

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

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:

• did-start-navigation
• did-navigate-in-page

Frame Navigation​

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.

Methods​

These methods can be accessed from the webContents module:

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 | null – 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.fromFrame(frame)​

• frame WebFrameMain

Returns WebContents | undefined – A WebContents instance with the given WebFrameMain, or undefined if there is no WebContents associated with the given WebFrameMain.

webContents.fromDevToolsTargetId(targetId)​

• 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)
}

Class: WebContents​

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.

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.

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

Emitted when the document in the top-level 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: ‘content-bounds-updated’​

Returns:

• event Event
• bounds 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().

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. Unrecognized options are not filtered out.
  • referrer Referrer – 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 (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 or 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.

See window.open() for more details and how to use this in conjunction with webContents.setWindowOpenHandler.

Event: ‘will-navigate’​

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 to false for this event.
  • isMainFrame boolean – True if the navigation is taking place in a main frame.
  • frame WebFrameMain – The frame to be navigated.
  • initiator WebFrameMain (optional) – The frame which initiated the navigation, which can be a parent frame (e.g. via window.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 Deprecated
• isInPlace boolean Deprecated
• isMainFrame boolean Deprecated
• frameProcessId Integer Deprecated
• frameRoutingId 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.

Event: ‘will-frame-navigate’​

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 to false for this event.
  • isMainFrame boolean – True if the navigation is taking place in a main frame.
  • frame WebFrameMain – The frame to be navigated.
  • initiator WebFrameMain (optional) – The frame which initiated the navigation, which can be a parent frame (e.g. via window.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.

Event: ‘did-start-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 – The frame to be navigated.
  • initiator WebFrameMain (optional) – The frame which initiated the navigation, which can be a parent frame (e.g. via window.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 Deprecated
• isInPlace boolean Deprecated
• isMainFrame boolean Deprecated
• frameProcessId Integer Deprecated
• frameRoutingId Integer Deprecated

Emitted when any frame (including main) starts navigating.

Event: ‘will-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 – The frame to be navigated.
  • initiator WebFrameMain (optional) – The frame which initiated the navigation, which can be a parent frame (e.g. via window.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 Deprecated
• isInPlace boolean Deprecated
• isMainFrame boolean Deprecated
• frameProcessId Integer Deprecated
• frameRoutingId 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).

Event: ‘did-redirect-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 – The frame to be navigated.
  • initiator WebFrameMain (optional) – The frame which initiated the navigation, which can be a parent frame (e.g. via window.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 Deprecated
• isInPlace boolean Deprecated
• isMainFrame boolean Deprecated
• frameProcessId Integer Deprecated
• frameRoutingId 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.

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.

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.

Event: ‘render-process-gone’​

Returns:

• event Event
• details RenderProcessGoneDetails

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: ‘input-event’​

Returns:

• event Event
• inputEvent InputEvent

Emitted when an input event is sent to the WebContents. See InputEvent for details.

Event: ‘before-input-event’​

Returns:

• event Event
• input Object – Input properties.
  • type string – Either keyUp or keyDown.
  • 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)
})

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: ‘blur’​

Emitted when the WebContents loses focus.

Event: ‘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.

Event: ‘devtools-open-url’​

Returns:

• event Event
• url 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.

Event: ‘devtools-search-query’​

Returns:

• event Event
• query string – text to query for.

Emitted when ‘Search’ is selected for text in its context menu.

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
• callback Function
  • isTrusted 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.

Event: ‘select-client-certificate’​

Returns:

• event Event
• url URL
• certificateList Certificate[]
• callback Function
  • certificate 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.

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.

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: ‘audio-state-changed’​

Returns:

• event Event<>
  • audible boolean – True if one or more frames or child webContents are emitting audio.

Emitted when media becomes audible or inaudible.

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:

<meta name='theme-color' content='#ff0000'>

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 (optional)
• scale Float (optional) – scaling factor for the custom cursor.
• size Size (optional) – the size of the image.
• 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.

Event: ‘context-menu’​

Returns:

• event Event
• params Object
  • x Integer – x coordinate.
  • y Integer – y coordinate.
  • frame WebFrameMain – Frame from which the context menu was invoked.
  • 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 – 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 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.
  • formControlType string – The source that the context menu was invoked on. Possible values include none, 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, and text-area,
  • 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[]
• callback Function
  • deviceId 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.

main.js

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)
    }
  })
})

Event: ‘paint’​

Returns:

• event Event
• dirtyRect Rectangle
• image 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')

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<string, string> – The other <webview> parameters such as the src 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.

Event: ‘did-attach-webview’​

Returns:

• event Event
• webContents WebContents – The guest web contents that is used by the <webview>.

Emitted when a <webview> 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 IpcMainEvent
• channel 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.

Event: ‘ipc-message-sync’​

Returns:

• event IpcMainEvent
• channel 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.

Event: ‘preferred-size-changed’​

Returns:

• event Event
• preferredSize 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.

Event: ‘frame-created’​

Returns:

• event Event
• details Object
  • frame WebFrameMain

Emitted when the mainFrame, an <iframe>, or a nested <iframe> is loaded within the page.

Instance Methods​

contents.loadURL(url[, options])​

• url string
• options 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 specified url 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)

contents.loadFile(filePath[, options])​

• filePath string
• options Object (optional)
  • query Record<string, string> (optional) – Passed to url.format().
  • search string (optional) – Passed to url.format().
  • hash string (optional) – Passed to url.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')

contents.downloadURL(url[, options])​

• url string
• options 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.

contents.getURL()​

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)
})

contents.getTitle()​

Returns string – The title of the current web page.

contents.isDestroyed()​

Returns boolean – Whether the web page is destroyed.

contents.close([opts])​

• opts Object (optional)
  • waitForBeforeUnload boolean – if true, fire the beforeunload event before closing the page. If the page prevents the unload, the WebContents will not be closed. The will-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.

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.

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()
  }
})

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 ‘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; }')
})

contents.removeInsertedCSS(key)​

• 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)
})

contents.executeJavaScript(code[, userGesture])​

• code string
• userGesture boolean (optional) – Default is false.

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
  })

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[]
• userGesture boolean (optional) – Default is false.

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.

contents.setIgnoreMenuShortcuts(ignore)​

• ignore boolean

Ignore application menu shortcuts while this web contents is focused.

contents.setWindowOpenHandler(handler)​

• handler Function<WindowOpenHandlerResponse>
  • 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 or other.
    • referrer Referrer – 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 (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 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
    }
  }
})

contents.setAudioMuted(muted)​

• muted boolean

Mute the audio on the current web page.

contents.isAudioMuted()​

Returns boolean – Whether this page has been muted.

contents.isCurrentlyAudible()​

Returns boolean – Whether audio is currently playing.

contents.setZoomFactor(factor)​

• 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.

contents.getZoomFactor()​

Returns number – the current zoom factor.

contents.setZoomLevel(level)​

• 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.

contents.getZoomLevel()​

Returns number – the current zoom level.

contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)​

• minimumLevel number
• maximumLevel 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)

contents.undo()​

Executes the editing command undo in web page.

contents.redo()​

Executes the editing command redo in web page.

contents.cut()​

Executes the editing command cut in web page.

contents.copy()​

Executes the editing command copy in web page.

contents.centerSelection()​

Centers the current text selection in web page.

contents.copyImageAt(x, y)​

• x Integer
• y Integer

Copy the image at the given position to the clipboard.

contents.paste()​

Executes the editing command paste in web page.

contents.pasteAndMatchStyle()​

Executes the editing command pasteAndMatchStyle in web page.

contents.delete()​

Executes the editing command delete in web page.

contents.selectAll()​

Executes the editing command selectAll in web page.

contents.unselect()​

Executes the editing command unselect in web page.

contents.scrollToTop()​

Scrolls to the top of the current webContents.

contents.scrollToBottom()​

Scrolls to the bottom of the current webContents.

contents.adjustSelection(options)​

• options Object
  • start 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:

contents.replace(text)​

• text string

Executes the editing command replace in web page.

contents.replaceMisspelling(text)​

• text string

Executes the editing command replaceMisspelling in web page.

contents.insertText(text)​

• text string

Returns Promise<void>

Inserts text to the focused element.

contents.findInPage(text[, options])​

• text string – Content to be searched, must not be empty.
• options Object (optional)
  • forward boolean (optional) – Whether to search forward or backward, defaults to true.
  • findNext boolean (optional) – Whether to begin a new text finding session with this request. Should be true for initial requests, and false for follow-up requests. Defaults to false.
  • matchCase boolean (optional) – Whether search should be case-sensitive, defaults to false.

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.

contents.stopFindInPage(action)​

• action string – Specifies the action to take place when ending webContents.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)

contents.capturePage([rect, opts])​

• 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 is false.
  • stayAwake boolean (optional) – Keep the system awake instead of allowing it to sleep. Default is false.

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.

contents.isBeingCaptured()​

Returns boolean – Whether this page is being captured. It returns true when the capturer count is large then 0.

contents.getPrintersAsync()​

Get the system printer list.

Returns Promise<PrinterInfo[]> – Resolves with a PrinterInfo[]

contents.print([options], [callback])​

• options Object (optional)
  • silent boolean (optional) – Don’t ask user for print settings. Default is false.
  • printBackground boolean (optional) – Prints the background color and image of the web page. Default is false.
  • 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 is true.
  • margins Object (optional)
    • marginType string (optional) – Can be default, none, printableArea, or custom. If custom is chosen, you will also need to specify top, bottom, left, and right.
    • 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 is false.
  • 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 be simplex, shortEdge, or longEdge.
  • dpi Record (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 be A0, A1, A2, A3, A4, A5, A6, Legal, Letter, Tabloid or an Object containing height and width.
• 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)
})

contents.printToPDF(options)​

• options Object
  • landscape 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 be A0, A1, A2, A3, A4, A5, A6, Legal, Letter, Tabloid, Ledger, or an Object containing height and width in inches. Defaults to Letter.
  • 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) and totalPages (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 the headerTemplate.
  • 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.

contents.addWorkSpace(path)​

• 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)
})

contents.removeWorkSpace(path)​

• path string

Removes the specified path from DevTools workspace.

contents.setDevToolsWebContents(devToolsWebContents)​

• 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:

main.js

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' })
})

contents.openDevTools([options])​

• options Object (optional)
  • mode string – Opens the devtools with specified dock state, can be left, right, bottom, undocked, detach. Defaults to last used dock state. In undocked mode it’s possible to dock back. In detach mode it’s not.
  • activate boolean (optional) – Whether to bring the opened devtools window to the foreground. The default is true.
  • title string (optional) – A title for the DevTools window (only in undocked or detach 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'.

contents.closeDevTools()​

Closes the devtools.

contents.isDevToolsOpened()​

Returns boolean – Whether the devtools is opened.

contents.isDevToolsFocused()​

Returns boolean – Whether the devtools view is focused .

contents.getDevToolsTitle()​

Returns string – the current title of the DevTools window. This will only be visible if DevTools is opened in undocked or detach mode.

contents.setDevToolsTitle(title)​

• 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.

contents.toggleDevTools()​

Toggles the developer tools.

contents.inspectElement(x, y)​

• x Integer
• y Integer

Starts inspecting element at position (x, y).

contents.inspectSharedWorker()​

Opens the developer tools for the shared worker context.

contents.inspectSharedWorkerById(workerId)​

• workerId string

Inspects the shared worker based on its ID.

contents.getAllSharedWorkers()​

Returns SharedWorkerInfo[] – Information about all Shared Workers.

contents.inspectServiceWorker()​

Opens the developer tools for the service worker context.

contents.send(channel, ...args)​

• 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.

contents.sendToFrame(frameId, channel, ...args)​

• 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)
})

contents.postMessage(channel, message, [transfer])​

• channel string
• message any
• transfer 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
  // ...
})

contents.enableDeviceEmulation(parameters)​

• parameters Object
  • screenPosition 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.

contents.disableDeviceEmulation()​

Disable device emulation enabled by webContents.enableDeviceEmulation.

contents.sendInputEvent(inputEvent)​

• 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.

contents.beginFrameSubscription([onlyDirty ,]callback)​

• onlyDirty boolean (optional) – Defaults to false.
• callback Function
  • image NativeImage
  • dirtyRect 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.

contents.endFrameSubscription()​

End subscribing for frame presentation events.

contents.startDrag(item)​

• item Object
  • file string – The path to the file being dragged.
  • files string[] (optional) – The paths to the files being dragged. (files will override file 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.

contents.savePage(fullPath, saveType)​

• 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)
  })
})

contents.showDefinitionForSelection() macOS​

Shows pop-up dictionary that searches the selected word on the page.

contents.isOffscreen()​

Returns boolean – Indicates whether offscreen rendering is enabled.

contents.startPainting()​

If offscreen rendering is enabled and not painting, start painting.

contents.stopPainting()​

If offscreen rendering is enabled and painting, stop painting.

contents.isPainting()​

Returns boolean – If offscreen rendering is enabled returns whether it is currently painting.

contents.setFrameRate(fps)​

• fps Integer

If offscreen rendering is enabled sets the frame rate to the specified number. Only values between 1 and 240 are accepted.

contents.getFrameRate()​

Returns Integer – If offscreen rendering is enabled returns the current frame rate.

contents.invalidate()​

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.

contents.getWebRTCIPHandlingPolicy()​

Returns string – Returns the WebRTC IP Handling Policy.

contents.setWebRTCIPHandlingPolicy(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.

contents.getWebRTCUDPPortRange()​

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.

contents.setWebRTCUDPPortRange(udpPortRange)​

• udpPortRange Object
  • min 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 }.

contents.getMediaSourceId(requestWebContents)​

• 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.

contents.getOSProcessId()​

Returns Integer – The operating system pid of the associated renderer process.

contents.getProcessId()​

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)

contents.takeHeapSnapshot(filePath)​

• 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.

contents.getBackgroundThrottling()​

Returns boolean – whether or not this WebContents will throttle animations and timers when the page becomes backgrounded. This also affects the Page Visibility API.

contents.setBackgroundThrottling(allowed)​

• 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.

contents.getType()​

Returns string – the type of the webContent. Can be backgroundPage, window, browserView, remote, webview or offscreen.

contents.setImageAnimationPolicy(policy)​

• policy string – Can be animate, animateOnce or noAnimation.

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.

Instance Properties​

contents.ipc Readonly​

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:

1. contents.on('ipc-message')
2. contents.mainFrame.on(channel)
3. contents.ipc.on(channel)
4. 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.

1. contents.mainFrame.handle(channel)
2. contents.handle(channel)
3. 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.

contents.audioMuted​

A boolean property that determines whether this page is muted.

contents.userAgent​

A string property that determines the user agent for this web page.

contents.zoomLevel​

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.

contents.zoomFactor​

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.

contents.frameRate​

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.

contents.id Readonly​

A Integer representing the unique ID of this WebContents. Each ID is unique among all WebContents instances of the entire Electron application.

contents.session Readonly​

A Session used by this webContents.

contents.navigationHistory Readonly​

A NavigationHistory used by this webContents.

contents.hostWebContents Readonly​

A WebContents instance that might own this WebContents.

contents.devToolsWebContents Readonly​

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.

contents.debugger Readonly​

A Debugger instance for this webContents.

contents.backgroundThrottling​

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.

contents.mainFrame Readonly​

A WebFrameMain property that represents the top frame of the page’s frame hierarchy.

contents.opener Readonly​

A WebFrameMain property that represents the frame that opened this WebContents, either with open(), or by navigating a link with a target attribute.

utilityProcess creates a child process with Node.js and Message ports enabled. It provides the equivalent of child_process.fork API from Node.js but instead uses Services API from Chromium to launch the child process.

Process: Main

Methods​

utilityProcess.fork(modulePath[, args][, options])​

• modulePath string – Path to the script that should run as entrypoint in the child process.
• args string[] (optional) – List of string arguments that will be available as process.argv in the child process.
• options Object (optional)
  • env Object (optional) – Environment key-value pairs. Default is process.env.
  • execArgv string[] (optional) – List of string arguments passed to the executable.
  • cwd string (optional) – Current working directory of the child process.
  • stdio (string[] | string) (optional) – Allows configuring the mode for stdout and stderr of the child process. Default is inherit. String value can be one of pipe, ignore, inherit, for more details on these values you can refer to stdio documentation from Node.js. Currently this option only supports configuring stdout and stderr to either pipe, inherit or ignore. Configuring stdin to any property other than ignore is not supported and will result in an error. For example, the supported values will be processed as following:
    • pipe: equivalent to [‘ignore’, ‘pipe’, ‘pipe’]
    • ignore: equivalent to [‘ignore’, ‘ignore’, ‘ignore’]
    • inherit: equivalent to [‘ignore’, ‘inherit’, ‘inherit’] (the default)
  • serviceName string (optional) – Name of the process that will appear in name property of ProcessMetric returned by app.getAppMetrics and child-process-gone event of app. Default is Node Utility Process.
  • allowLoadingUnsignedLibraries boolean (optional) macOS – With this flag, the utility process will be launched via the Electron Helper (Plugin).app helper executable on macOS, which can be codesigned with com.apple.security.cs.disable-library-validation and com.apple.security.cs.allow-unsigned-executable-memory entitlements. This will allow the utility process to load unsigned libraries. Unless you specifically need this capability, it is best to leave this disabled. Default is false.

Returns UtilityProcess

Class: UtilityProcess​

Instances of the UtilityProcess represent the Chromium spawned child process with Node.js integration.

UtilityProcess is an EventEmitter.

Instance Methods​

child.postMessage(message, [transfer])​

• message any
• transfer MessagePortMain[] (optional)

Send a message to the child process, optionally transferring ownership of zero or more MessagePortMain objects.

For example:

// Main process
const { port1, port2 } = new MessageChannelMain()
const child = utilityProcess.fork(path.join(__dirname, 'test.js'))
child.postMessage({ message: 'hello' }, [port1])

// Child process
process.parentPort.once('message', (e) => {
  const [port] = e.ports
  // ...
})

child.kill()​

Returns boolean

Terminates the process gracefully. On POSIX, it uses SIGTERM but will ensure the process is reaped on exit. This function returns true if the kill is successful, and false otherwise.

Instance Properties​

child.pid​

A Integer | undefined representing the process identifier (PID) of the child process. If the child process fails to spawn due to errors, then the value is undefined. When the child process exits, then the value is undefined after the exit event is emitted.

child.stdout​

A NodeJS.ReadableStream | null that represents the child process’s stdout. If the child was spawned with options.stdio[1] set to anything other than ‘pipe’, then this will be null. When the child process exits, then the value is null after the exit event is emitted.

// Main process
const { port1, port2 } = new MessageChannelMain()
const child = utilityProcess.fork(path.join(__dirname, 'test.js'))
child.stdout.on('data', (data) => {
  console.log(Received chunk ${data})
})

child.stderr​

A NodeJS.ReadableStream | null that represents the child process’s stderr. If the child was spawned with options.stdio[2] set to anything other than ‘pipe’, then this will be null. When the child process exits, then the value is null after the exit event is emitted.

Instance Events​

Event: ‘spawn’​

Emitted once the child process has spawned successfully.

Event: ‘exit’​

Returns:

• code number – Contains the exit code for the process obtained from waitpid on posix, or GetExitCodeProcess on windows.

Emitted after the child process ends.

Event: ‘message’​

Returns:

• message any

Emitted when the child process sends a message using process.parentPort.postMessage().

Class: Tray​

Add icons and context menus to the system’s notification area.

Process: Main

Tray is an EventEmitter.

const { app, Menu, Tray } = require('electron')

let tray = null
app.whenReady().then(() => {
  tray = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' },
    { label: 'Item3', type: 'radio', checked: true },
    { label: 'Item4', type: 'radio' }
  ])
  tray.setToolTip('This is my application.')
  tray.setContextMenu(contextMenu)
})

Platform Considerations

Linux

• Tray icon uses StatusNotifierItem by default, when it is not available in user’s desktop environment the GtkStatusIcon will be used instead.
• The click event is emitted when the tray icon receives activation from user, however the StatusNotifierItem spec does not specify which action would cause an activation, for some environments it is left mouse click, but for some it might be double left mouse click.
• In order for changes made to individual MenuItems to take effect, you have to call setContextMenu again. For example:

const { app, Menu, Tray } = require('electron')

let appIcon = null
app.whenReady().then(() => {
  appIcon = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' }
  ])

  // Make a change to the context menu
  contextMenu.items[1].checked = false

  // Call this again for Linux because we modified the context menu
  appIcon.setContextMenu(contextMenu)
})

MacOS

• Icons passed to the Tray constructor should be Template Images.
• To make sure your icon isn’t grainy on retina monitors, be sure your @2x image is 144dpi.
• If you are bundling your application (e.g., with webpack for development), be sure that the file names are not being mangled or hashed. The filename needs to end in Template, and the @2x image needs to have the same filename as the standard image, or MacOS will not magically invert your image’s colors or use the high density image.
• 16×16 (72dpi) and 32×32@2x (144dpi) work well for most icons.

Windows

• It is recommended to use ICO icons to get best visual effects.

new Tray(image, [guid])​

• image (NativeImage | string)
• guid string (optional) Windows – Assigns a GUID to the tray icon. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.

Creates a new tray icon associated with the image.

Instance Events​

The Tray module emits the following events:

Event: ‘click’​

Returns:

• event KeyboardEvent
• bounds Rectangle – The bounds of tray icon.
• position Point – The position of the event.

Emitted when the tray icon is clicked.

Note that on Linux this event is emitted when the tray icon receives an activation, which might not necessarily be left mouse click.

Event: ‘right-click’ macOS Windows​

Returns:

• event KeyboardEvent
• bounds Rectangle – The bounds of tray icon.

Emitted when the tray icon is right clicked.

Event: ‘double-click’ macOS Windows​

Returns:

• event KeyboardEvent
• bounds Rectangle – The bounds of tray icon.

Emitted when the tray icon is double clicked.

Event: ‘middle-click’ Windows​

Returns:

• event KeyboardEvent
• bounds Rectangle – The bounds of tray icon.

Emitted when the tray icon is middle clicked.

Event: ‘balloon-show’ Windows​

Emitted when the tray balloon shows.

Event: ‘balloon-click’ Windows​

Emitted when the tray balloon is clicked.

Event: ‘balloon-closed’ Windows​

Emitted when the tray balloon is closed because of timeout or user manually closes it.

Event: ‘drop’ macOS​

Emitted when any dragged items are dropped on the tray icon.

Event: ‘drop-files’ macOS​

Returns:

• event Event
• files string[] – The paths of the dropped files.

Emitted when dragged files are dropped in the tray icon.

Event: ‘drop-text’ macOS​

Returns:

• event Event
• text string – the dropped text string.

Emitted when dragged text is dropped in the tray icon.

Event: ‘drag-enter’ macOS​

Emitted when a drag operation enters the tray icon.

Event: ‘drag-leave’ macOS​

Emitted when a drag operation exits the tray icon.

Event: ‘drag-end’ macOS​

Emitted when a drag operation ends on the tray or ends at another location.

Event: ‘mouse-up’ macOS​

Returns:

• event KeyboardEvent
• position Point – The position of the event.

Emitted when the mouse is released from clicking the tray icon.

Note: This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.

Event: ‘mouse-down’ macOS​

Returns:

• event KeyboardEvent
• position Point – The position of the event.

Emitted when the mouse clicks the tray icon.

Event: ‘mouse-enter’ macOS Windows​

Returns:

• event KeyboardEvent
• position Point – The position of the event.

Emitted when the mouse enters the tray icon.

Event: ‘mouse-leave’ macOS Windows​

Returns:

• event KeyboardEvent
• position Point – The position of the event.

Emitted when the mouse exits the tray icon.

Event: ‘mouse-move’ macOS Windows​

Returns:

• event KeyboardEvent
• position Point – The position of the event.

Emitted when the mouse moves in the tray icon.

Instance Methods​

The Tray class has the following methods:

tray.destroy()​

Destroys the tray icon immediately.

tray.setImage(image)​

• image (NativeImage | string)

Sets the image associated with this tray icon.

tray.setPressedImage(image) macOS​

• image (NativeImage | string)

Sets the image associated with this tray icon when pressed on macOS.

tray.setToolTip(toolTip)​

• toolTip string

Sets the hover text for this tray icon.

tray.setTitle(title[, options]) macOS​

• title string
• options Object (optional)
  • fontType string (optional) – The font family variant to display, can be monospaced or monospacedDigit. monospaced is available in macOS 10.15+ When left blank, the title uses the default system font.

Sets the title displayed next to the tray icon in the status bar (Support ANSI colors).

tray.getTitle() macOS​

Returns string – the title displayed next to the tray icon in the status bar

tray.setIgnoreDoubleClickEvents(ignore) macOS​

• ignore boolean

Sets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.

This value is set to false by default.

tray.getIgnoreDoubleClickEvents() macOS​

Returns boolean – Whether double click events will be ignored.

tray.displayBalloon(options) Windows​

• options Object
  • icon (NativeImage | string) (optional) – Icon to use when iconType is custom.
  • iconType string (optional) – Can be none, info, warning, error or custom. Default is custom.
  • title string
  • content string
  • largeIcon boolean (optional) – The large version of the icon should be used. Default is true. Maps to NIIF_LARGE_ICON.
  • noSound boolean (optional) – Do not play the associated sound. Default is false. Maps to NIIF_NOSOUND.
  • respectQuietTime boolean (optional) – Do not display the balloon notification if the current user is in “quiet time”. Default is false. Maps to NIIF_RESPECT_QUIET_TIME.

Displays a tray balloon.

tray.removeBalloon() Windows​

Removes a tray balloon.

tray.focus() Windows​

Returns focus to the taskbar notification area. Notification area icons should use this message when they have completed their UI operation. For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use tray.focus() to return focus to the notification area.

tray.popUpContextMenu([menu, position]) macOS Windows​

• menu Menu (optional)
• position Point (optional) – The pop up position.

Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon’s context menu.

The position is only available on Windows, and it is (0, 0) by default.

tray.closeContextMenu() macOS Windows​

Closes an open context menu, as set by tray.setContextMenu().

tray.setContextMenu(menu)​

• menu Menu | null

Sets the context menu for this icon.

tray.getBounds() macOS Windows​

Returns Rectangle

The bounds of this tray icon as Object.

tray.isDestroyed()​

Returns boolean – Whether the tray icon is destroyed.

Class: TouchBar​

Create TouchBar layouts for native macOS applications

Process: Main

new TouchBar(options)​

• options Object
  • items (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer)[] (optional)
  • escapeItem (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopover | TouchBarScrubber | TouchBarSegmentedControl | TouchBarSlider | TouchBarSpacer | null) (optional)

Creates a new touch bar with the specified items. Use BrowserWindow.setTouchBar to add the TouchBar to a window.

Note: The TouchBar API is currently experimental and may change or be removed in future Electron releases.

Tip: If you don’t have a MacBook with Touch Bar, you can use Touch Bar Simulator to test Touch Bar usage in your app.

Static Properties​

TouchBarButton​

A typeof TouchBarButton reference to the TouchBarButton class.

TouchBarColorPicker​

A typeof TouchBarColorPicker reference to the TouchBarColorPicker class.

TouchBarGroup​

A typeof TouchBarGroup reference to the TouchBarGroup class.

TouchBarLabel​

A typeof TouchBarLabel reference to the TouchBarLabel class.

TouchBarPopover​

A typeof TouchBarPopover reference to the TouchBarPopover class.

TouchBarScrubber​

A typeof TouchBarScrubber reference to the TouchBarScrubber class.

TouchBarSegmentedControl​

A typeof TouchBarSegmentedControl reference to the TouchBarSegmentedControl class.

TouchBarSlider​

A typeof TouchBarSlider reference to the TouchBarSlider class.

TouchBarSpacer​

A typeof TouchBarSpacer reference to the TouchBarSpacer class.

TouchBarOtherItemsProxy​

A typeof TouchBarOtherItemsProxy reference to the TouchBarOtherItemsProxy class.

Instance Properties​

The following properties are available on instances of TouchBar:

touchBar.escapeItem​

A TouchBarItem that will replace the “esc” button on the touch bar when set. Setting to null restores the default “esc” button. Changing this value immediately updates the escape item in the touch bar.

Examples​

Below is an example of a simple slot machine touch bar game with a button and some labels.

const { app, BrowserWindow, TouchBar } = require('electron')

const { TouchBarLabel, TouchBarButton, TouchBarSpacer } = TouchBar

let spinning = false

// Reel labels
const reel1 = new TouchBarLabel({ label: '' })
const reel2 = new TouchBarLabel({ label: '' })
const reel3 = new TouchBarLabel({ label: '' })

// Spin result label
const result = new TouchBarLabel({ label: '' })

// Spin button
const spin = new TouchBarButton({
  label: '🎰 Spin',
  backgroundColor: '#7851A9',
  click: () => {
    // Ignore clicks if already spinning
    if (spinning) {
      return
    }

    spinning = true
    result.label = ''

    let timeout = 10
    const spinLength = 4 * 1000 // 4 seconds
    const startTime = Date.now()

    const spinReels = () => {
      updateReels()

      if ((Date.now() - startTime) >= spinLength) {
        finishSpin()
      } else {
        // Slow down a bit on each spin
        timeout *= 1.1
        setTimeout(spinReels, timeout)
      }
    }

    spinReels()
  }
})

const getRandomValue = () => {
  const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇', '🍀']
  return values[Math.floor(Math.random() * values.length)]
}

const updateReels = () => {
  reel1.label = getRandomValue()
  reel2.label = getRandomValue()
  reel3.label = getRandomValue()
}

const finishSpin = () => {
  const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size
  if (uniqueValues === 1) {
    // All 3 values are the same
    result.label = '💰 Jackpot!'
    result.textColor = '#FDFF00'
  } else if (uniqueValues === 2) {
    // 2 values are the same
    result.label = '😍 Winner!'
    result.textColor = '#FDFF00'
  } else {
    // No values are the same
    result.label = '🙁 Spin Again'
    result.textColor = null
  }
  spinning = false
}

const touchBar = new TouchBar({
  items: [
    spin,
    new TouchBarSpacer({ size: 'large' }),
    reel1,
    new TouchBarSpacer({ size: 'small' }),
    reel2,
    new TouchBarSpacer({ size: 'small' }),
    reel3,
    new TouchBarSpacer({ size: 'large' }),
    result
  ]
})

let window

app.whenReady().then(() => {
  window = new BrowserWindow({
    frame: false,
    titleBarStyle: 'hiddenInset',
    width: 200,
    height: 200,
    backgroundColor: '#000'
  })
  window.loadURL('about:blank')
  window.setTouchBar(touchBar)
})

Running the above example​

To run the example above, you’ll need to (assuming you’ve got a terminal open in the directory you want to run the example):

1. Save the above file to your computer as touchbar.js
2. Install Electron via npm install electron
3. Run the example inside Electron: ./node_modules/.bin/electron touchbar.js

You should then see a new Electron window and the app running in your touch bar (or touch bar emulator).

Get system preferences.

Process: Main, Utility

const { systemPreferences } = require('electron')
console.log(systemPreferences.isAeroGlassEnabled())

Events​

The systemPreferences object emits the following events:

Event: ‘accent-color-changed’ Windows​

Returns:

• event Event
• newColor string – The new RGBA color the user assigned to be their system accent color.

Event: ‘color-changed’ Windows​

Returns:

• event Event

Methods​

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS​

Returns boolean – Whether the Swipe between pages setting is on.

systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOS​

• event string
• userInfo Record<string, any>
• deliverImmediately boolean (optional) – true to post notifications immediately even when the subscribing app is inactive.

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.postLocalNotification(event, userInfo) macOS​

• event string
• userInfo Record<string, any>

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.postWorkspaceNotification(event, userInfo) macOS​

• event string
• userInfo Record<string, any>

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.subscribeNotification(event, callback) macOS​

• event string | null
• callback Function
  • event string
  • userInfo Record<string, unknown>
  • object string

Returns number – The ID of this subscription

Subscribes to native notifications of macOS, callback will be called with callback(event, userInfo) when the corresponding event happens. The userInfo is an Object that contains the user information dictionary sent along with the notification. The object is the sender of the notification, and only supports NSString values for now.

The id of the subscriber is returned, which can be used to unsubscribe the event.

Under the hood this API subscribes to NSDistributedNotificationCenter, example values of event are:

• AppleInterfaceThemeChangedNotification
• AppleAquaColorVariantChanged
• AppleColorPreferencesChangedNotification
• AppleShowScrollBarsSettingChanged

If event is null, the NSDistributedNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.subscribeLocalNotification(event, callback) macOS​

• event string | null
• callback Function
  • event string
  • userInfo Record<string, unknown>
  • object string

Returns number – The ID of this subscription

Same as subscribeNotification, but uses NSNotificationCenter for local defaults. This is necessary for events such as NSUserDefaultsDidChangeNotification.

If event is null, the NSNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS​

• event string | null
• callback Function
  • event string
  • userInfo Record<string, unknown>
  • object string

Returns number – The ID of this subscription

Same as subscribeNotification, but uses NSWorkspace.sharedWorkspace.notificationCenter. This is necessary for events such as NSWorkspaceDidActivateApplicationNotification.

If event is null, the NSWorkspaceNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.unsubscribeNotification(id) macOS​

• id Integer

Removes the subscriber with id.

systemPreferences.unsubscribeLocalNotification(id) macOS​

• id Integer

Same as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.

systemPreferences.unsubscribeWorkspaceNotification(id) macOS​

• id Integer

Same as unsubscribeNotification, but removes the subscriber from NSWorkspace.sharedWorkspace.notificationCenter.

systemPreferences.registerDefaults(defaults) macOS​

• defaults Record<string, string | boolean | number> – a dictionary of (key: value) user defaults

Add the specified defaults to your application’s NSUserDefaults.

systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOS​

• key string
• type Type – Can be string, boolean, integer, float, double, url, array or dictionary.

Returns UserDefaultTypes[Type] – The value of key in NSUserDefaults.

Some popular key and types are:

• AppleInterfaceStyle: string
• AppleAquaColorVariant: integer
• AppleHighlightColor: string
• AppleShowScrollBars: string
• NSNavRecentPlaces: array
• NSPreferredWebServices: dictionary
• NSUserDictionaryReplacementItems: array

systemPreferences.setUserDefault<Type extends keyof UserDefaultTypes>(key, type, value) macOS​

• key string
• type Type – Can be string, boolean, integer, float, double, url, array or dictionary.
• value UserDefaultTypes[Type]

Set the value of key in NSUserDefaults.

Note that type should match actual type of value. An exception is thrown if they don’t.

Some popular key and types are:

• ApplePressAndHoldEnabled: boolean

systemPreferences.removeUserDefault(key) macOS​

• key string

Removes the key in NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.

systemPreferences.isAeroGlassEnabled() Windows​

Returns boolean – true if DWM composition (Aero Glass) is enabled, and false otherwise.

An example of using it to determine if you should create a transparent window or not (transparent windows won’t work correctly when DWM composition is disabled):

const { BrowserWindow, systemPreferences } = require('electron')
const browserOptions = { width: 1000, height: 800 }

// Make the window transparent only if the platform supports it.
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
  browserOptions.transparent = true
  browserOptions.frame = false
}

// Create the window.
const win = new BrowserWindow(browserOptions)

// Navigate.
if (browserOptions.transparent) {
  win.loadFile('index.html')
} else {
  // No transparency, so we load a fallback that uses basic styles.
  win.loadFile('fallback.html')
}

systemPreferences.getAccentColor() Windows macOS​

Returns string – The users current system wide accent color preference in RGBA hexadecimal form.

const color = systemPreferences.getAccentColor() // "aabbccdd"
const red = color.substr(0, 2) // "aa"
const green = color.substr(2, 2) // "bb"
const blue = color.substr(4, 2) // "cc"
const alpha = color.substr(6, 2) // "dd"

This API is only available on macOS 10.14 Mojave or newer.

systemPreferences.getColor(color) Windows macOS​

• color string – One of the following values:
  • On Windows:
    • 3d-dark-shadow – Dark shadow for three-dimensional display elements.
    • 3d-face – Face color for three-dimensional display elements and for dialog box backgrounds.
    • 3d-highlight – Highlight color for three-dimensional display elements.
    • 3d-light – Light color for three-dimensional display elements.
    • 3d-shadow – Shadow color for three-dimensional display elements.
    • active-border – Active window border.
    • active-caption – Active window title bar. Specifies the left side color in the color gradient of an active window’s title bar if the gradient effect is enabled.
    • active-caption-gradient – Right side color in the color gradient of an active window’s title bar.
    • app-workspace – Background color of multiple document interface (MDI) applications.
    • button-text – Text on push buttons.
    • caption-text – Text in caption, size box, and scroll bar arrow box.
    • desktop – Desktop background color.
    • disabled-text – Grayed (disabled) text.
    • highlight – Item(s) selected in a control.
    • highlight-text – Text of item(s) selected in a control.
    • hotlight – Color for a hyperlink or hot-tracked item.
    • inactive-border – Inactive window border.
    • inactive-caption – Inactive window caption. Specifies the left side color in the color gradient of an inactive window’s title bar if the gradient effect is enabled.
    • inactive-caption-gradient – Right side color in the color gradient of an inactive window’s title bar.
    • inactive-caption-text – Color of text in an inactive caption.
    • info-background – Background color for tooltip controls.
    • info-text – Text color for tooltip controls.
    • menu – Menu background.
    • menu-highlight – The color used to highlight menu items when the menu appears as a flat menu.
    • menubar – The background color for the menu bar when menus appear as flat menus.
    • menu-text – Text in menus.
    • scrollbar – Scroll bar gray area.
    • window – Window background.
    • window-frame – Window frame.
    • window-text – Text in windows.
  • On macOS
    • control-background – The background of a large interface element, such as a browser or table.
    • control – The surface of a control.
    • control-text -The text of a control that isn’t disabled.
    • disabled-control-text – The text of a control that’s disabled.
    • find-highlight – The color of a find indicator.
    • grid – The gridlines of an interface element such as a table.
    • header-text – The text of a header cell in a table.
    • highlight – The virtual light source onscreen.
    • keyboard-focus-indicator – The ring that appears around the currently focused control when using the keyboard for interface navigation.
    • label – The text of a label containing primary content.
    • link – A link to other content.
    • placeholder-text – A placeholder string in a control or text view.
    • quaternary-label – The text of a label of lesser importance than a tertiary label such as watermark text.
    • scrubber-textured-background – The background of a scrubber in the Touch Bar.
    • secondary-label – The text of a label of lesser importance than a normal label such as a label used to represent a subheading or additional information.
    • selected-content-background – The background for selected content in a key window or view.
    • selected-control – The surface of a selected control.
    • selected-control-text – The text of a selected control.
    • selected-menu-item-text – The text of a selected menu.
    • selected-text-background – The background of selected text.
    • selected-text – Selected text.
    • separator – A separator between different sections of content.
    • shadow – The virtual shadow cast by a raised object onscreen.
    • tertiary-label – The text of a label of lesser importance than a secondary label such as a label used to represent disabled text.
    • text-background – Text background.
    • text – The text in a document.
    • under-page-background – The background behind a document’s content.
    • unemphasized-selected-content-background – The selected content in a non-key window or view.
    • unemphasized-selected-text-background – A background for selected text in a non-key window or view.
    • unemphasized-selected-text – Selected text in a non-key window or view.
    • window-background – The background of a window.
    • window-frame-text – The text in the window’s titlebar area.

Returns string – The system color setting in RGBA hexadecimal form (#RRGGBBAA). See the Windows docs and the macOS docs for more details.

The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, and unemphasized-selected-text.

systemPreferences.getSystemColor(color) macOS​

• color string – One of the following values:
  • blue
  • brown
  • gray
  • green
  • orange
  • pink
  • purple
  • red
  • yellow

Returns string – The standard system color formatted as #RRGGBBAA.

Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like ‘Increase contrast’ and ‘Reduce transparency’. See Apple Documentation for more details.

systemPreferences.getEffectiveAppearance() macOS​

Returns string – Can be dark, light or unknown.

Gets the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance

systemPreferences.canPromptTouchID() macOS​

Returns boolean – whether or not this device has the ability to use Touch ID.

systemPreferences.promptTouchID(reason) macOS​

• reason string – The reason you are asking for Touch ID authentication

Returns Promise<void> – resolves if the user has successfully authenticated with Touch ID.

const { systemPreferences } = require('electron')

systemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {
  console.log('You have successfully authenticated with Touch ID!')
}).catch(err => {
  console.log(err)
})

This API itself will not protect your user data; rather, it is a mechanism to allow you to do so. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. This could be done with node-keytar, such that one would store an encryption key with node-keytar and only fetch it if promptTouchID() resolves.

systemPreferences.isTrustedAccessibilityClient(prompt) macOS​

• prompt boolean – whether or not the user will be informed via prompt if the current process is untrusted.

Returns boolean – true if the current process is a trusted accessibility client and false if it is not.

systemPreferences.getMediaAccessStatus(mediaType) Windows macOS​

• mediaType string – Can be microphone, camera or screen.

Returns string – Can be not-determined, granted, denied, restricted or unknown.

This user consent was not required on macOS 10.13 High Sierra so this method will always return granted. macOS 10.14 Mojave or higher requires consent for microphone and camera access. macOS 10.15 Catalina or higher requires consent for screen access.

Windows 10 has a global setting controlling microphone and camera access for all win32 applications. It will always return granted for screen and for all media types on older versions of Windows.

systemPreferences.askForMediaAccess(mediaType) macOS​

• mediaType string – the type of media being requested; can be microphone, camera.

Returns Promise<boolean> – A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.

Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app’s Info.plist file. The values for these keys will be used to populate the permission dialogs so that the user will be properly informed as to the purpose of the permission request. See Electron Application Distribution for more information about how to set these in the context of Electron.

This user consent was not required until macOS 10.14 Mojave, so this method will always return true if your system is running 10.13 High Sierra.

systemPreferences.getAnimationSettings()​

Returns Object:

• shouldRenderRichAnimation boolean – Returns true if rich animations should be rendered. Looks at session type (e.g. remote desktop) and accessibility settings to give guidance for heavy animations.
• scrollAnimationsEnabledBySystem boolean – Determines on a per-platform basis whether scroll animations (e.g. produced by home/end key) should be enabled.
• prefersReducedMotion boolean – Determines whether the user desires reduced motion based on platform APIs.

Returns an object with system animation settings.

Properties​

systemPreferences.accessibilityDisplayShouldReduceTransparency() macOS​

A boolean property which determines whether the app avoids using semitransparent backgrounds. This maps to NSWorkspace.accessibilityDisplayShouldReduceTransparency

systemPreferences.effectiveAppearance macOS Readonly​

A string property that can be dark, light or unknown.

Returns the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance

Manage files and URLs using their default applications.

Process: Main, Renderer (non-sandboxed only)

The shell module provides functions related to desktop integration.

An example of opening a URL in the user’s default browser:

const { shell } = require('electron')

shell.openExternal('https://github.com')

Note: While the shell module can be used in the renderer process, it will not function in a sandboxed renderer.

Methods​

The shell module has the following methods:

shell.showItemInFolder(fullPath)​

• fullPath string

Show the given file in a file manager. If possible, select the file.

shell.openPath(path)​

• path string

Returns Promise<string> – Resolves with a string containing the error message corresponding to the failure if a failure occurred, otherwise “”.

Open the given file in the desktop’s default manner.

shell.openExternal(url[, options])​

• url string – Max 2081 characters on windows.
• options Object (optional)
  • activate boolean (optional) macOS – true to bring the opened application to the foreground. The default is true.
  • workingDirectory string (optional) Windows – The working directory.
  • logUsage boolean (optional) Windows – Indicates a user initiated launch that enables tracking of frequently used programs and other behaviors. The default is false.

Returns Promise<void>

Open the given external protocol URL in the desktop’s default manner. (For example, mailto: URLs in the user’s default mail agent).

shell.trashItem(path)​

• path string – path to the item to be moved to the trash.

Returns Promise<void> – Resolves when the operation has been completed. Rejects if there was an error while deleting the requested item.

This moves a path to the OS-specific trash location (Trash on macOS, Recycle Bin on Windows, and a desktop-environment-specific location on Linux).

shell.beep()​

Play the beep sound.

shell.writeShortcutLink(shortcutPath[, operation], options) Windows​

• shortcutPath string
• operation string (optional) – Default is create, can be one of following:
  • create – Creates a new shortcut, overwriting if necessary.
  • update – Updates specified properties only on an existing shortcut.
  • replace – Overwrites an existing shortcut, fails if the shortcut doesn’t exist.
• options ShortcutDetails

Returns boolean – Whether the shortcut was created successfully.

Creates or updates a shortcut link at shortcutPath.

shell.readShortcutLink(shortcutPath) Windows​

• shortcutPath string

Returns ShortcutDetails

Resolves the shortcut link at shortcutPath.

An exception will be thrown when any error happens.

The ShareMenu class creates Share Menu on macOS, which can be used to share information from the current context to apps, social media accounts, and other services.

For including the share menu as a submenu of other menus, please use the shareMenu role of MenuItem.

Class: ShareMenu​

Create share menu on macOS.

Process: Main

new ShareMenu(sharingItem)​

• sharingItem SharingItem – The item to share.

Creates a new share menu.

Instance Methods​

The shareMenu object has the following instance methods:

shareMenu.popup([options])​

• options PopupOptions (optional)
  • browserWindow BrowserWindow (optional) – Default is the focused window.
  • x number (optional) – Default is the current mouse cursor position. Must be declared if y is declared.
  • y number (optional) – Default is the current mouse cursor position. Must be declared if x is declared.
  • positioningItem number (optional) macOS – The index of the menu item to be positioned under the mouse cursor at the specified coordinates. Default is -1.
  • callback Function (optional) – Called when menu is closed.

Pops up this menu as a context menu in the BrowserWindow.

shareMenu.closePopup([browserWindow])​

• browserWindow BrowserWindow (optional) – Default is the focused window.

Closes the context menu in the browserWindow.