Event: open-file (macOS only)
Emitted when the user wants to open a file with the application. Returns event Event and path string. The open-file event is usually emitted when the application is already open and the OS wants to reuse the application to open the file. It is also emitted when a file is dropped onto the dock and the application is not yet running. Make sure to listen for the open-file event very early in your application startup to handle this case (even before the ready event is emitted). You should call event.preventDefault() if you want to handle this event. On Windows, you have to parse process.argv (in the main process) to get the filepath.
Event: did-become-active (macOS only)
Emitted when the application becomes active. Returns event Event. This differs from the activate event in that did-become-active is emitted every time the app becomes active, not only when Dock icon is clicked or application is re-launched. It is also emitted when a user switches to the app via the macOS App Switcher.
Event: browser-window-blur
Emitted when a browserWindow gets blurred. Returns event Event and window BrowserWindow.
Event: browser-window-created
Emitted when a new browserWindow is created. Returns event Event and window BrowserWindow.
Event: login example
Example showing how to handle login requests:
const { app } = require('electron')
app.on('login', (event, webContents, details, authInfo, callback) => {
event.preventDefault()
callback('username', 'secret')
})
Event: certificate-error example
Example showing how to handle certificate errors:
const { app } = require('electron')
app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
if (url === 'https://github.com') {
// Verification logic.
event.preventDefault()
callback(true)
} else {
callback(false)
}
})
Event: will-finish-launching
Emitted when the application has finished basic startup. On Windows and Linux, this event is the same as the ready event. On macOS, this event represents the applicationWillFinishLaunching notification of NSApplication. In most cases, you should do everything in the ready event handler instead.
Event: open-url (macOS only)
Emitted when the user wants to open a URL with the application. Returns event Event and url string. Your application's Info.plist file must define the URL scheme within the CFBundleURLTypes key and set NSPrincipalClass to AtomApplication. Be sure to register a listener for the open-url event early in your application startup to detect if the application is being opened to handle a URL. If you register the listener in response to a ready event, you'll miss URLs that trigger the launch of your application.
Event: activate (macOS only)
Emitted when the application is activated. Returns event Event and hasVisibleWindows boolean. Various actions can trigger this event, such as launching the application for the first time, attempting to re-launch the application when it's already running, or clicking on the application's dock or taskbar icon.
Event: certificate-error
Emitted when failed to verify the certificate for url, to trust the certificate you should prevent the default behavior with event.preventDefault() and call callback(true). Returns event Event, webContents WebContents, url string, error string (error code), certificate Certificate, callback Function with isTrusted boolean parameter, and isMainFrame boolean.
Event: ready
Emitted once, when Electron has finished initializing. Returns event Event and launchInfo Record<string, any> | NotificationResponse (macOS only). On macOS, launchInfo holds the userInfo of NSUserNotification or information from UNNotificationResponse that was used to open the application if launched from Notification Center. You can call app.isReady() to check if this event has already fired and app.whenReady() to get a Promise that is fulfilled when Electron is initialized. The ready event is only fired after the main process has finished running the first tick of the event loop. If an Electron API needs to be called before the ready event, ensure it is called synchronously in the top-level context of the main process.
Event: select-client-certificate
Emitted when a client certificate is requested. Returns event Event, webContents WebContents (optional, null when request does not originate from a renderer process), url URL, certificateList Certificate[], and callback Function with optional certificate Certificate parameter. The url corresponds to the navigation entry requesting the client certificate and callback can be called with an entry filtered from the list. Using event.preventDefault() prevents the application from using the first certificate from the store. webContents is null when the request does not originate from a renderer process, for example when using net.request or net.fetch in the main process, or from a utility process created with respondToAuthRequestsFromMainProcess: true.
Event: will-continue-activity (macOS only)
Emitted during Handoff before an activity from a different device wants to be resumed. Returns event Event and type string (identifying the activity, maps to NSUserActivity.activityType). You should call event.preventDefault() if you want to handle this event.
Event: accessibility-support-changed (macOS Windows only)
Emitted when Chromium's accessibility support changes. This event fires when assistive technologies, such as screen readers, are enabled or disabled. Returns event Event and accessibilitySupportEnabled boolean (true when Chromium's accessibility support is enabled, false otherwise). See https://www.chromium.org/developers/design-documents/accessibility for more details.
Event: update-activity-state (macOS only)
Emitted when Handoff is about to be resumed on another device. Returns event Event, type string (identifying the activity, maps to NSUserActivity.activityType), and userInfo unknown (app-specific state stored by the activity). If you need to update the state to be transferred, you should call event.preventDefault() immediately, construct a new userInfo dictionary and call app.updateCurrentActivity() in a timely manner. Otherwise, the operation will fail and continue-activity-error will be called.
Event: window-all-closed
Emitted when all windows have been closed. If you do not subscribe to this event and all windows are closed, the default behavior is to quit the app. However, if you subscribe, you control whether the app quits or not. If the user pressed Cmd+Q or the developer called app.quit(), Electron will first try to close all the windows and then emit the will-quit event, and in this case the window-all-closed event would not be emitted.
Event: continue-activity-error (macOS only)
Emitted during Handoff when an activity from a different device fails to be resumed. Returns event Event, type string (identifying the activity, maps to NSUserActivity.activityType), and error string (localized description of the error).
Event: browser-window-focus
Emitted when a browserWindow gets focused. Returns event Event and window BrowserWindow.
Event: before-quit
Emitted before the application starts closing its windows. Returns event Event. Calling event.preventDefault() will prevent the default behavior, which is terminating the application. On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout. If application quit was initiated by autoUpdater.quitAndInstall(), then before-quit is emitted after emitting close event on all windows and closing them.
Event: web-contents-created
Emitted when a new webContents is created. Returns event Event and webContents WebContents.
Event: continue-activity (macOS only)
Emitted during Handoff when an activity from a different device wants to be resumed. Returns event Event, type string (identifying the activity, maps to NSUserActivity.activityType), userInfo unknown (app-specific state stored by the activity on another device), and details Object with optional webpageURL string (URL of the webpage accessed by the activity on another device). You should call event.preventDefault() if you want to handle this event. A user activity can be continued only in an app that has the same developer Team ID as the activity's source app and that supports the activity's type. Supported activity types are specified in the app's Info.plist under the NSUserActivityTypes key.
Event: login
Emitted when webContents or Utility process wants to do basic auth. Returns event Event, webContents WebContents (optional), authenticationResponseDetails Object (url URL, pid number, isRequestForNavigation boolean, firstAuthAttempt boolean, responseHeaders Record<string, string | string[]> optional), authInfo Object (isProxy boolean, scheme string, host string, port Integer, realm string), and callback Function (username string optional, password string optional). The default behavior is to cancel all authentications. To override this you should prevent the default behavior with event.preventDefault() and call callback(username, password) with the credentials. If callback is called without a username or password, the authentication request will be cancelled and the authentication error will be returned to the page.
Event: will-quit
Emitted when all windows have been closed and the application will quit. Returns event Event. Calling event.preventDefault() will prevent the default behavior, which is terminating the application. See the description of the window-all-closed event for the differences between will-quit and window-all-closed events. On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.
Event: gpu-info-update
Emitted whenever there is a GPU info update.
Event: select-client-certificate example
Example showing how to handle client certificate selection:
const { app } = require('electron')
app.on('select-client-certificate', (event, webContents, url, list, callback) => {
event.preventDefault()
callback(list[0])
})
Event: did-resign-active (macOS only)
Emitted when the app is no longer active and doesn't have focus. This can be triggered, for example, by clicking on another application or by using the macOS App Switcher to switch to another application. Returns event Event.
Event: quit
Emitted when the application is quitting. Returns event Event and exitCode Integer. On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.
Event: child-process-gone
Emitted when the child process unexpectedly disappears. This is normally because it was crashed or killed. It does not include renderer processes. Returns event Event and details Object with: type string (process type: Utility, Zygote, Sandbox helper, GPU, Pepper Plugin, Pepper Plugin Broker, Unknown), reason string (clean-exit, abnormal-exit, killed, crashed, oom, launch-failed, integrity-failure, memory-eviction), exitCode number (exit code for the process), serviceName string (optional, non-localized name of the process), name string (optional, name of the process, examples: Audio Service, Content Decryption Module Service, Network Service, Video Capture).
Event: activity-was-continued (macOS only)
Emitted during Handoff after an activity from this device was successfully resumed on another one. Returns event Event, type string (identifying the activity, maps to NSUserActivity.activityType), and userInfo unknown (app-specific state stored by the activity).
Event: session-created
Emitted when Electron has created a new session. Returns session Session.
Event: session-created example
Example showing how to listen for session creation:
const { app } = require('electron')
app.on('session-created', (session) => {
console.log(session)
})
Event: second-instance
This event is emitted inside the primary instance of your application when a second instance has been executed and calls app.requestSingleInstanceLock(). Returns event Event, argv string[] (array of the second instance's command line arguments), workingDirectory string (second instance's working directory), and additionalData unknown (JSON object of additional data passed from the second instance). Usually applications respond to this by making their primary window focused and non-minimized. argv will not be exactly the same list of arguments as those passed to the second instance. The order might change and additional arguments might be appended. If you need to maintain the exact same arguments, use additionalData instead. If the second instance is started by a different user than the first, the argv array will not include the arguments. This event is guaranteed to be emitted after the ready event of app gets emitted. Extra command line arguments might be added by Chromium, such as --original-process-start-time.
Event: new-window-for-tab (macOS only)
Emitted when the user clicks the native macOS new tab button. Returns event Event. The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier. You must create a window in this handler in order for macOS tabbing to work as expected.
Cookies 'changed' event
The 'changed' event is emitted when a cookie is changed because it was added, edited, removed, or expired. It passes an event object, a Cookie object representing the cookie that was changed, a cause string indicating the change reason, and a removed boolean (true if the cookie was removed, false otherwise). Cause values are: 'inserted' (cookie was inserted), 'inserted-no-change-overwrite' (newly inserted cookie overwrote an identical cookie with no change), 'inserted-no-value-change-overwrite' (newly inserted cookie overwrote but only changed web-observable properties like expiry), 'explicit' (cookie deleted directly by consumer action), 'overwrite' (cookie automatically removed due to insert operation), 'expired' (cookie automatically removed as it expired), 'evicted' (cookie automatically evicted during garbage collection), and 'expired-overwrite' (cookie overwritten with already-expired expiration date).
Debugger message event
The 'message' event is emitted whenever the debugging target issues an instrumentation event. It returns event, method, params, and sessionId parameters. The method parameter is a string with the method name. The params parameter contains event parameters defined by the 'parameters' attribute in the remote debugging protocol. The sessionId parameter is a unique identifier of the attached debugging session that will match the value sent from debugger.sendCommand.
Debugger detach event
The 'detach' event is emitted when the debugging session is terminated. It returns event and reason parameters, where reason is a string explaining the reason for detaching the debugger. This happens either when webContents is closed or DevTools is invoked for the attached webContents.
DownloadItem 'updated' event
The 'updated' event is emitted when the download has been updated and is not done. It returns two parameters: event (Event) and state (string). The state can be 'progressing' (the download is in-progress) or 'interrupted' (the download has interrupted and can be resumed).
DownloadItem 'done' event
The 'done' event is emitted when the download is in a terminal state, including a completed download, a cancelled download (via downloadItem.cancel()), and an interrupted download that cannot be resumed. It returns two parameters: event (Event) and state (string). The state can be 'completed' (the download completed successfully), 'cancelled' (the download has been cancelled), or 'interrupted' (the download has interrupted and cannot resume).
Listen for transactions-updated before calling purchaseProduct
You should listen for the transactions-updated event as soon as possible and certainly before calling purchaseProduct.
inAppPurchase transactions-updated event
The 'transactions-updated' event is emitted when one or more transactions have been updated. The event callback receives an event object and a transactions array containing Transaction objects.
menu-will-show event
Emitted when menu.popup() is called. The event object is returned.
menu-will-close event
Emitted when a popup is closed either manually or with menu.closePopup(). The event object is returned.
nativeTheme 'updated' event
The nativeTheme module emits an 'updated' event when something in the underlying NativeTheme changes. This normally means that either shouldUseDarkColors, shouldUseHighContrastColors, or shouldUseInvertedColorScheme has changed. You must check these properties to determine which one has changed.
powerMonitor 'suspend' event
The 'suspend' event is emitted when the system is suspending.
powerMonitor 'unlock-screen' event
The 'unlock-screen' event is emitted as soon as the system's screen is unlocked. Available on macOS and Windows.
powerMonitor 'user-did-become-active' event
The 'user-did-become-active' event is emitted when a login session is activated. Available on macOS only.
powerMonitor 'speed-limit-change' event
The 'speed-limit-change' event notifies of a change in the operating system's advertised speed limit for CPUs. Available on macOS and Windows. The event returns a details object with a limit property that is a number representing the speed limit in percent. Values below 100 indicate the system is reducing processing power due to thermal management.
powerMonitor 'lock-screen' event
The 'lock-screen' event is emitted when the system is about to lock the screen. Available on macOS and Windows.
powerMonitor 'shutdown' event
The 'shutdown' event is emitted when the system is about to reboot or shut down. Available on Linux and macOS. If the event handler invokes e.preventDefault(), Electron will attempt to delay system shutdown to allow the app to exit cleanly. If e.preventDefault() is called, the app should exit as soon as possible by calling app.quit().
powerMonitor 'thermal-state-change' event
The 'thermal-state-change' event is emitted when the thermal state of the system changes. Available on macOS only. The event returns a details object with a state property that is a string which can be 'unknown', 'nominal', 'fair', 'serious', or 'critical'. This indicates the system's new thermal state. Depending on the severity, the system might throttle the CPU or switch on fans. The same state might be received repeatedly.
powerMonitor 'on-battery' event
The 'on-battery' event is emitted when the system changes to battery power. Available on macOS and Windows.
powerMonitor 'on-ac' event
The 'on-ac' event is emitted when the system changes to AC power. Available on macOS and Windows.
powerMonitor 'resume' event
The 'resume' event is emitted when the system is resuming.
powerMonitor 'user-did-resign-active' event
The 'user-did-resign-active' event is emitted when a login session is deactivated. Available on macOS only.
process 'loaded' event
The 'loaded' event is emitted when Electron has loaded its internal initialization script and is beginning to load the web page or the main script.
display-removed event
The display-removed event is emitted when a display has been removed. It returns event Event and oldDisplay Display.
display-metrics-changed event
The display-metrics-changed event is emitted when one or more metrics change in a display. It returns event Event, display Display, and changedMetrics string[]. Possible changes in changedMetrics are: bounds, workArea, scaleFactor, and rotation.
display-added event
The display-added event is emitted when a new display has been added. It returns event Event and newDisplay Display.
ServiceWorkers registration-completed event
The 'registration-completed' event is emitted when a service worker has been registered, either after navigator.serviceWorker.register('/sw.js') successfully resolves or when a Chrome extension is loaded. It returns an Event object and details object containing scope (string - the base URL that the service worker is registered for).
ServiceWorkers console-message event
The 'console-message' event is emitted when a service worker logs something to the console. It returns an Event object and messageDetails object. messageDetails contains: message (string - the actual console message), versionId (number - the version ID of the service worker), source (string - one of: javascript, xml, network, console-api, storage, rendering, security, deprecation, worker, violation, intervention, recommendation, or other), level (number - log level 0 to 3 matching verbose, info, warning, error), sourceUrl (string - the URL the message came from), and lineNumber (number - the line number that triggered this console message).