screen.getPrimaryDisplay()
Returns Display. Returns the primary display.
app/methods
526 notes in this subject, read out of this brain and free to use. This is page 5 of 9.
screen.getAllDisplays()
Returns Display[]. Returns an array of displays that are currently available.
screen.getCursorScreenPoint()
Returns Point. Returns the current absolute position of the mouse pointer. The return value is a DIP point, not a screen physical point. Not supported on Wayland (Linux).
screen.getDisplayNearestPoint()
Takes point Point as parameter. Returns Display. Returns the display nearest the specified point.
screen.getDisplayMatching()
Takes rect Rectangle as parameter. Returns Display. Returns the display that most closely intersects the provided bounds.
serviceWorkers.getFromVersionID() method deprecated
The getFromVersionID(versionId) method is deprecated. It takes a versionId parameter (number - ID of the service worker version) and returns ServiceWorkerInfo - information about that service worker. If the service worker does not exist or is not running, this method throws an exception. Use serviceWorkers.getInfoFromVersionID instead.
startWorkerForScope example
const { app, session } = require('electron') const { serviceWorkers } = session.defaultSession // Collect service workers scopes const workerScopes = Object.values(serviceWorkers.getAllRunning()).map((info) => info.scope) app.on('browser-window-created', async (event, window) => { for (const scope of workerScopes) { try { // Ensure worker is started const serviceWorker = await serviceWorkers.startWorkerForScope(scope) serviceWorker.send('window-created', { windowId: window.id }) } catch (error) { console.error(`Failed to start service worker for ${scope}`) console.error(error) } } })
serviceWorkers.startWorkerForScope() method experimental
The startWorkerForScope(scope) method is experimental. It takes a scope parameter (string - the scope of the service worker to start) and returns Promise<ServiceWorkerMain> - resolves with the service worker when it's started. It starts the service worker or does nothing if already running.
serviceWorkers.getWorkerFromVersionID() method experimental
The getWorkerFromVersionID(versionId) method is experimental. It takes a versionId parameter (number - ID of the service worker version) and returns ServiceWorkerMain | undefined - an instance of the service worker associated with the given version ID. If there's no associated version, or its running status has changed to 'stopped', this will return undefined.
serviceWorkers.getAllRunning() method
The getAllRunning() method returns Record<number, ServiceWorkerInfo> - a ServiceWorkerInfo object where the keys are the service worker version ID and the values are the information about that service worker.
shell.beep method
shell.beep() plays the beep sound.
shell.trashItem method
shell.trashItem(path) moves a path to the OS-specific trash location (Trash on macOS, Recycle Bin on Windows, and a desktop-environment-specific location on Linux). Parameter: path (string) - path to the item to be moved to the trash. Must use the default path separator for the platform (backslash on Windows). Use path.resolve() from the node:path module to ensure correct handling on all filesystems. Returns Promise<void> that resolves when the operation has been completed and rejects if there was an error while deleting the requested item.
shell.openExternal method
shell.openExternal(url[, options]) opens the given external protocol URL in the desktop's default manner (for example, mailto: URLs in the user's default mail agent). Returns Promise<void>. Parameter url (string) has a max length of 2081 characters on Windows. Options object is optional with properties: activate (boolean, optional, macOS only, default true) to bring the opened application to foreground, workingDirectory (string, optional, Windows only) for the working directory, and logUsage (boolean, optional, Windows only, default false) to indicate a user-initiated launch that enables tracking of frequently used programs and other behaviors.
shell.openPath method
shell.openPath(path) opens the given file in the desktop's default manner. Parameter: path (string). Returns Promise<string> that resolves with a string containing the error message if a failure occurred, otherwise an empty string.
shell.showItemInFolder method
shell.showItemInFolder(fullPath) shows the given file in a file manager. If possible, it selects the file. Parameter: fullPath (string).
shell.readShortcutLink method
shell.readShortcutLink(shortcutPath) resolves the shortcut link at shortcutPath. Windows only. Parameter: shortcutPath (string). Returns ShortcutDetails. An exception will be thrown when any error happens.
shell.writeShortcutLink method
shell.writeShortcutLink(shortcutPath[, operation], options) creates or updates a shortcut link at shortcutPath. Windows only. Parameters: shortcutPath (string), operation (string, optional, default 'create') which can be 'create' (creates a new shortcut, overwriting if necessary), 'update' (updates specified properties only on an existing shortcut), or 'replace' (overwrites an existing shortcut, fails if the shortcut doesn't exist), and options (ShortcutDetails object). Returns boolean indicating whether the shortcut was created successfully.
shell.openExternal example
const { shell } = require('electron') shell.openExternal('https://github.com')
SharedTextureImportedSubtle.getVideoFrame
getVideoFrame is a method that returns a VideoFrame object using the imported shared texture in the current process. You can call VideoFrame.close() once finished using the object. The underlying resources will wait for GPU finish internally.
SharedTextureImportedSubtle.release
release is a method that releases the resources. If you transferred and got multiple SharedTextureImported objects, you have to release every one of them. The resource on the GPU process will be destroyed when the last one is released. It accepts an optional callback parameter (Function) that is called when the GPU command buffer finishes using this shared texture, providing a precise event to safely release dependent resources.
SharedTextureImportedSubtle.startTransferSharedTexture
startTransferSharedTexture is a method that returns a SharedTextureTransfer object, which can be serialized and transferred to other processes.
SharedTextureImportedSubtle.getFrameCreationSyncToken
getFrameCreationSyncToken is an advanced method that returns a SharedTextureSyncToken. It is typically called after finishTransferSharedTexture and should be passed to the object which called startTransferSharedTexture to prevent the source object from releasing the underlying resource before the target object actually acquires the reference at the GPU process asynchronously.
SharedTextureImportedSubtle.setReleaseSyncToken
setReleaseSyncToken is an advanced method that accepts a syncToken parameter of type SharedTextureSyncToken. When used, this object's underlying resource will not be released until the set sync token is fulfilled at the GPU process. By using sync tokens, users are not required to use release callbacks for lifetime management.
SharedTextureTransfer to SharedTextureImportedSubtle conversion
Call sharedTexture.subtle.finishTransferSharedTexture to convert a SharedTextureTransfer object and receive a SharedTextureImportedSubtle object back.
TouchBarOtherItemsProxy constructor
TouchBarOtherItemsProxy is instantiated using the constructor: new TouchBarOtherItemsProxy()
systemPreferences.getAnimationSettings()
Returns an object with system animation settings containing: shouldRenderRichAnimation (boolean) - whether rich animations should be rendered based on session type and accessibility settings; scrollAnimationsEnabledBySystem (boolean) - whether scroll animations should be enabled on this platform; prefersReducedMotion (boolean) - whether the user desires reduced motion based on platform APIs.
systemPreferences.promptTouchID() example
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) })
systemPreferences.getAccentColor() example
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"
systemPreferences.postLocalNotification() macOS
Posts a native macOS local notification. Parameters: event (string) and userInfo (Record<string, any>). The userInfo is an object containing the user information dictionary sent along with the notification.
systemPreferences.postNotification() macOS
Posts a native macOS notification. Parameters: event (string), userInfo (Record<string, any>), and optional deliverImmediately (boolean, default false). When deliverImmediately is true, notifications are posted immediately even when the subscribing app is inactive.
systemPreferences.postWorkspaceNotification() macOS
Posts a native macOS workspace notification. Parameters: event (string) and userInfo (Record<string, any>). The userInfo is an object containing the user information dictionary sent along with the notification.
systemPreferences.subscribeNotification() macOS
Subscribes to native macOS notifications via NSDistributedNotificationCenter. Parameters: event (string | null) and callback (function receiving event string, userInfo Record<string, unknown>, and object string). Returns a numeric subscription ID which can be used to unsubscribe. When event is null, NSDistributedNotificationCenter does not use it as criteria for delivery. Example events: AppleInterfaceThemeChangedNotification, AppleAquaColorVariantChanged, AppleColorPreferencesChangedNotification, AppleShowScrollBarsSettingChanged.
systemPreferences.subscribeLocalNotification() macOS
Subscribes to native macOS local notifications via NSNotificationCenter. Parameters: event (string | null) and callback (function receiving event string, userInfo Record<string, unknown>, and object string). Returns a numeric subscription ID. Uses NSNotificationCenter for local defaults, necessary for events like NSUserDefaultsDidChangeNotification. When event is null, NSNotificationCenter does not use it as criteria for delivery.
systemPreferences.isTrustedAccessibilityClient() macOS
Returns a boolean indicating whether the current process is a trusted accessibility client. Returns true if trusted, false if not. Parameter: prompt (boolean) - whether or not the user will be informed via prompt if the current process is untrusted.
systemPreferences.askForMediaAccess() macOS
Requests user consent for media access. Parameter: mediaType (string) - can be 'microphone' or 'camera'. Returns Promise<boolean> resolving to true if consent was granted, false if denied. Rejects if invalid mediaType is passed. Requires NSMicrophoneUsageDescription and NSCameraUsageDescription strings set in app's Info.plist. If access was denied, it must be changed through System Preferences; restarting the app is required for new permissions to take effect. If access has already been requested and denied, an alert will not pop up and the promise will resolve with the existing access status. On macOS 10.13 High Sierra and earlier, always returns true.
systemPreferences.promptTouchID() macOS
Prompts the user for Touch ID authentication. Parameter: reason (string) - the reason for requesting Touch ID authentication. Returns a Promise<void> that resolves if the user has successfully authenticated with Touch ID. This API is a mechanism to allow you to protect your user data; it does not protect data itself. Native apps should set Access Control Constants like kSecAccessControlUserPresence on their keychain entry to auto-prompt for Touch ID biometric consent when reading the entry.
systemPreferences.getMediaAccessStatus() Windows and macOS
Gets the current media access permission status. Parameter: mediaType (string) - can be 'microphone', 'camera', or 'screen'. Returns a string: 'not-determined', 'granted', 'denied', 'restricted', or 'unknown'. On macOS 10.13 High Sierra, always returns 'granted' (consent not required). macOS 10.14 Mojave or higher requires consent for microphone and camera. macOS 10.15 Catalina or higher requires consent for screen. Windows 10 has a global setting for microphone and camera; always returns 'granted' for screen and on older Windows versions.
systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS
Returns a boolean indicating whether the Swipe between pages setting is enabled. This method is only available on macOS.
systemPreferences.subscribeWorkspaceNotification() macOS
Subscribes to macOS workspace notifications via NSWorkspace.sharedWorkspace.notificationCenter. Parameters: event (string | null) and callback (function receiving event string, userInfo Record<string, unknown>, and object string). Returns a numeric subscription ID. Necessary for events like NSWorkspaceDidActivateApplicationNotification. When event is null, NSWorkspaceNotificationCenter does not use it as criteria for delivery.
systemPreferences.unsubscribeLocalNotification() macOS
Removes a subscriber from NSNotificationCenter using the subscription ID (integer) previously returned by subscribeLocalNotification().
systemPreferences.unsubscribeWorkspaceNotification() macOS
Removes a subscriber from NSWorkspace.sharedWorkspace.notificationCenter using the subscription ID (integer) previously returned by subscribeWorkspaceNotification().
systemPreferences.registerDefaults() macOS
Adds specified defaults to the application's NSUserDefaults. Parameter: defaults (Record<string, string | boolean | number>) - a dictionary of key-value pairs.
systemPreferences.getUserDefault() macOS
Gets a user default value from NSUserDefaults. Parameters: key (string) and type (can be 'string', 'boolean', 'integer', 'float', 'double', 'url', 'array', or 'dictionary'). Returns the value of the specified type. Popular keys include: AppleInterfaceStyle (string), AppleAquaColorVariant (integer), AppleHighlightColor (string), AppleShowScrollBars (string), NSNavRecentPlaces (array), NSPreferredWebServices (dictionary), NSUserDictionaryReplacementItems (array).
systemPreferences.setUserDefault() macOS
Sets a user default value in NSUserDefaults. Parameters: key (string), type (can be 'string', 'boolean', 'integer', 'float', 'double', 'url', 'array', or 'dictionary'), and value (matching the specified type). An exception is thrown if the type does not match the value's actual type. Popular keys include ApplePressAndHoldEnabled (boolean).
systemPreferences.removeUserDefault() macOS
Removes a key from NSUserDefaults. Parameter: key (string). This can be used to restore the default or global value of a key previously set with setUserDefault.
systemPreferences.getAccentColor() macOS
Returns the user's current system-wide accent color preference as an RGBA hexadecimal string (format: "aabbccdd" where aa=red, bb=green, cc=blue, dd=alpha). Only available on macOS 10.14 Mojave or newer.
systemPreferences.getColor() Windows and macOS
Gets a system color setting in RGBA hexadecimal form (#RRGGBBAA). On Windows, valid color values include: 3d-dark-shadow, 3d-face, 3d-highlight, 3d-light, 3d-shadow, active-border, active-caption, active-caption-gradient, app-workspace, button-text, caption-text, desktop, disabled-text, highlight, highlight-text, hotlight, inactive-border, inactive-caption, inactive-caption-gradient, inactive-caption-text, info-background, info-text, menu, menu-highlight, menubar, menu-text, scrollbar, window, window-frame, window-text. On macOS, valid color values include: control-background, control, control-text, disabled-control-text, find-highlight, grid, header-text, highlight, keyboard-focus-indicator, label, link, placeholder-text, quaternary-label, scrubber-textured-background, secondary-label, selected-content-background, selected-control, selected-control-text, selected-menu-item-text, selected-text-background, selected-text, separator, shadow, tertiary-label, text-background, text, under-page-background, unemphasized-selected-content-background, unemphasized-selected-text-background, unemphasized-selected-text, window-background, window-frame-text. The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, unemphasized-selected-text.
systemPreferences.getSystemColor() macOS
Returns one of the standard macOS system colors formatted as #RRGGBBAA. Valid color values: blue, brown, gray, green, orange, pink, purple, red, yellow. These colors automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'.
systemPreferences.getEffectiveAppearance() macOS
Returns a string indicating the current macOS appearance setting applied to the application. Return value can be 'dark', 'light', or 'unknown'. Maps to NSApplication.effectiveAppearance.
systemPreferences.canPromptTouchID() macOS
Returns a boolean indicating whether the device has the ability to use Touch ID.
TouchBarSlider constructor options
The TouchBarSlider constructor accepts an options object with the following properties: label (string, optional) for label text; value (Integer, optional) for selected value; minValue (Integer, optional) for minimum value; maxValue (Integer, optional) for maximum value; change (Function, optional) a callback function to call when the slider is changed, which receives newValue (number) as the value that the user selected on the slider.
TouchBarSpacer constructor
TouchBarSpacer is instantiated with new TouchBarSpacer(options). The options parameter is an object with an optional 'size' property. The size property is a string that can be 'small' (default, maps to NSTouchBarItemIdentifierFixedSpaceSmall), 'large' (maps to NSTouchBarItemIdentifierFixedSpaceLarge), or 'flexible' (takes up all available space, maps to NSTouchBarItemIdentifierFlexibleSpace).
tray.setImage() method
tray.setImage(image) sets the image associated with the tray icon. image is a NativeImage or string.
tray.setToolTip() method
tray.setToolTip(toolTip) sets the hover text for the tray icon. toolTip is a string. Setting the text to an empty string removes the tooltip.
tray.setTitle() method
tray.setTitle(title[, options]) sets the title displayed next to the tray icon in the status bar on macOS. title is a string (required). options is an optional object with fontType (optional string, can be 'monospaced' or 'monospacedDigit'; monospaced is available in macOS 10.15+; when left blank, the default system font is used). The title supports ANSI colors.
tray.getTitle() method
tray.getTitle() returns a string containing the title displayed next to the tray icon in the status bar on macOS.
tray.getIgnoreDoubleClickEvents() method
tray.getIgnoreDoubleClickEvents() returns a boolean indicating whether double click events will be ignored on macOS.
tray.displayBalloon() method
tray.displayBalloon(options) displays a tray balloon on Windows. options is an object with: icon (optional NativeImage or string, used when iconType is 'custom'), iconType (optional string, can be 'none', 'info', 'warning', 'error' or 'custom'; default is 'custom'), title (required string), content (required string), largeIcon (optional boolean, default true, maps to NIIF_LARGE_ICON), noSound (optional boolean, default false, maps to NIIF_NOSOUND), respectQuietTime (optional boolean, default false, maps to NIIF_RESPECT_QUIET_TIME).
tray.removeBalloon() method
tray.removeBalloon() removes a tray balloon on Windows.
tray.focus() method
tray.focus() returns focus to the taskbar notification area on Windows. Notification area icons should use this method 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.