Create tray, dock, and application icons using PNG or JPG files. Process: Main, Renderer The nativeImage module provides a unified interface for manipulating system images. These can be handy if you want to provide multiple scaled versions of the same icon or take advantage of macOS template images. Electron APIs that take image files accept either file paths or NativeImage instances. An empty and transparent image will be used when null is passed. For example, when creating a Tray or setting a BrowserWindow‘s icon, you can either pass an image file path as a string: Main Process or generate a NativeImage instance from the same file: Main Process Supported Formats​ Currently, PNG and JPEG image formats are supported across all platforms. PNG is recommended because of its support for transparency and lossless compression. On Windows, you can also load ICO icons from file paths. For best visual quality, we recommend including at least the following sizes: Check the Icon Scaling section in the Windows App Icon Construction reference. NOTE EXIF metadata is currently not supported and will not be taken into account during image encoding and decoding. High Resolution Image​ On platforms that support high pixel density displays (such as Apple Retina), you can append @2x after image’s base filename to mark it as a 2x scale high resolution image. For example, if icon.png is a normal image that has standard resolution, then [email protected] will be treated as a high resolution image that has double Dots per Inch (DPI) density. If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes within Electron. For example: Main Process The following suffixes for DPI are also supported: Template Image macOS​ On macOS, template images consist of black and an alpha channel. Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance. The most common case is to use template images for a menu bar (Tray) icon, so it can adapt to both light and dark menu bars. To mark an image as a template image, its base filename should end with the word Template (e.g. xxxTemplate.png). You can also specify template images at different DPI densities (e.g. [email protected]). Methods​ The nativeImage module has the following methods, all of which return an instance of the NativeImage class: nativeImage.createEmpty()​ Returns NativeImage Creates an empty NativeImage instance. nativeImage.createThumbnailFromPath(path, size) macOS Windows​ Returns Promise<NativeImage> – fulfilled with the file’s thumbnail preview image, which is a NativeImage. Note: The Windows implementation will ignore size.height and scale the height according to size.width. nativeImage.createFromPath(path)​ Returns NativeImage Creates a new NativeImage instance from a file located at path. This method returns an empty image if the path does not exist, cannot be read, or is not a valid image. nativeImage.createFromBitmap(buffer, options)​ Returns NativeImage Creates a new NativeImage instance from buffer that contains the raw bitmap pixel data returned by toBitmap(). The specific format is platform-dependent. nativeImage.createFromBuffer(buffer[, options])​ Returns NativeImage Creates a new NativeImage instance from buffer. Tries to decode as PNG or JPEG first. nativeImage.createFromDataURL(dataURL)​ Returns NativeImage Creates a new NativeImage instance from dataUrl, a base 64 encoded Data URL string. nativeImage.createFromNamedImage(imageName[, hslShift]) macOS​ Returns NativeImage Creates a new NativeImage instance from the NSImage that maps to the given image name. See Apple’s NSImageName documentation for a list of possible values. The hslShift is applied to the image with the following rules: This means that [-1, 0, 1] will make the image completely white and [-1, 1, 0] will make the image completely black. In some cases, the NSImageName doesn’t match its string representation; one example of this is NSFolderImageName, whose string representation would actually be NSFolder. Therefore, you’ll need to determine the correct string representation for your image before passing it in. This can be done with the following: where SYSTEM_IMAGE_NAME should be replaced with any value from this list. Class: NativeImage​ Natively wrap images such as tray, dock, and application icons. Process: Main, RendererThis class is not exported from the ‘electron’ module. It is only available as a return value of other methods in the Electron API. Instance Methods​ The following methods are available on instances of the NativeImage class: image.toPNG([options])​ Returns Buffer – A Buffer that contains the image’s PNG encoded data. image.toJPEG(quality)​ Returns Buffer – A Buffer that contains the image’s JPEG encoded data. image.toBitmap([options])​ Returns Buffer – A Buffer that contains a copy of the image’s raw bitmap pixel data. image.toDataURL([options])​ Returns string – The Data URL of the image. image.getBitmap([options])​ Returns Buffer – A Buffer that contains the image’s raw bitmap pixel data. The difference between getBitmap() and toBitmap() is that getBitmap() does not copy the bitmap data, so you have to use the returned Buffer immediately in current event loop tick; otherwise the data might be changed or destroyed. image.getNativeHandle() macOS​ Returns Buffer – A Buffer that stores C pointer to underlying native handle of the image. On macOS, a pointer to NSImage instance is returned. Notice that the returned pointer is a weak pointer to the underlying native image instead of a copy, so you must ensure that the associated nativeImage instance is kept around. image.isEmpty()​ Returns boolean – Whether the image is empty. image.getSize([scaleFactor])​ Returns Size. If scaleFactor is passed, this will return the size corresponding to the image representation most closely matching the passed value. image.setTemplateImage(option)​ Marks the image as a macOS template image. image.isTemplateImage()​ Returns boolean – Whether the image is a macOS template image. image.crop(rect)​ Returns NativeImage – The cropped image. image.resize(options)​ Returns NativeImage – The resized image. If only the height or the width are specified then the current aspect ratio will be preserved in the resized image. image.getAspectRatio([scaleFactor])​ Returns Number – The image’s aspect ratio (width divided by height). If scaleFactor is passed, this will return the aspect ratio corresponding to the image representation most closely matching the passed value. image.getScaleFactors()​ Returns Number[] – An array of all scale factors corresponding to representations for a given NativeImage. image.addRepresentation(options)​ Add an image representation for a specific scale factor. This can be used to programmatically add different scale factor representations to an image. This can be called on empty images. Instance Properties​ nativeImage.isMacTemplateImage macOS​ A boolean property that determines whether the image is considered a template image. Please note that this property only has an effect on macOS.

MessagePortMain is the main-process-side equivalent of the DOM MessagePort object. It behaves similarly to the DOM version, with the exception that it uses the Node.js EventEmitter event system, instead of the DOM EventTarget system. This means you should use port.on(‘message’, …) to listen for events, instead of port.onmessage = … or port.addEventListener(‘message’, …) See the Channel Messaging API documentation for more information on using channel messaging. MessagePortMain is an EventEmitter. Class: MessagePortMain​ Port interface for channel messaging in the main process. Process: MainThis class is not exported from the ‘electron’ module. It is only available as a return value of other methods in the Electron API. Instance Methods​ port.postMessage(message, [transfer])​ Sends a message from the port, and optionally, transfers ownership of objects to other browsing contexts. port.start()​ Starts the sending of messages queued on the port. Messages will be queued until this method is called. port.close()​ Disconnects the port, so it is no longer active. Instance Events​ Event: ‘message’​ Returns: Emitted when a MessagePortMain object receives a message. Event: ‘close’​ Emitted when the remote end of a MessagePortMain object becomes disconnected.

MessageChannelMain is the main-process-side equivalent of the DOM MessageChannel object. Its singular function is to create a pair of connected MessagePortMain objects. See the Channel Messaging API documentation for more information on using channel messaging. Class: MessageChannelMain​ Channel interface for channel messaging in the main process. Process: Main Example: Instance Properties​ channel.port1​ A MessagePortMain property. channel.port2​ A MessagePortMain property.

Class: Menu​ Create native application menus and context menus. Process: Main new Menu()​ Creates a new menu. Static Methods​ The Menu class has the following static methods: Menu.setApplicationMenu(menu)​ Sets menu as the application menu on macOS. On Windows and Linux, the menu will be set as each window’s top menu. Also on Windows and Linux, you can use a & in the top-level item name to indicate which letter should get a generated accelerator. For example, using &File for the file menu would result in a generated Alt-F accelerator that opens the associated menu. The indicated character in the button label then gets an underline, and the & character is not displayed on the button label. In order to escape the & character in an item name, add a proceeding &. For example, &&File would result in &File displayed on the button label. Passing null will suppress the default menu. On Windows and Linux, this has the additional effect of removing the menu bar from the window. Note: The default menu will be created automatically if the app does not set one. It contains standard items such as File, Edit, View, Window and Help. Menu.getApplicationMenu()​ Returns Menu | null – The application menu, if set, or null, if not set. Note: The returned Menu instance doesn’t support dynamic addition or removal of menu items. Instance properties can still be dynamically modified. Menu.sendActionToFirstResponder(action) macOS​ Sends the action to the first responder of application. This is used for emulating default macOS menu behaviors. Usually you would use the role property of a MenuItem. See the macOS Cocoa Event Handling Guide for more information on macOS’ native actions. Menu.buildFromTemplate(template)​ Returns Menu Generally, the template is an array of options for constructing a MenuItem. The usage can be referenced above. You can also attach other fields to the element of the template and they will become properties of the constructed menu items. Instance Methods​ The menu object has the following instance methods: menu.popup([options])​ Pops up this menu as a context menu in the BrowserWindow. menu.closePopup([browserWindow])​ Closes the context menu in the browserWindow. menu.append(menuItem)​ Appends the menuItem to the menu. menu.getMenuItemById(id)​ Returns MenuItem | null the item with the specified id menu.insert(pos, menuItem)​ Inserts the menuItem to the pos position of the menu. Instance Events​ Objects created with new Menu or returned by Menu.buildFromTemplate emit the following events: Note: Some events are only available on specific operating systems and are labeled as such. Event: ‘menu-will-show’​ Returns: Emitted when menu.popup() is called. Event: ‘menu-will-close’​ Returns: Emitted when a popup is closed either manually or with menu.closePopup(). Instance Properties​ menu objects also have the following properties: menu.items​ A MenuItem[] array containing the menu’s items. Each Menu consists of multiple MenuItems and each MenuItem can have a submenu. Examples​ An example of creating the application menu with the simple template API: Render process​ To create menus initiated by the renderer process, send the required information to the main process using IPC and have the main process display the menu on behalf of the renderer. Below is an example of showing a menu when the user right clicks the page: Notes on macOS Application Menu​ macOS has a completely different style of application menu from Windows and Linux. Here are some notes on making your app’s menu more native-like. Standard Menus​ On macOS there are many system-defined standard menus, like the Services and Windows menus. To make your menu a standard menu, you should set your menu’s role to one of the following and Electron will recognize them and make them become standard menus: Standard Menu Item Actions​ macOS has provided standard actions for some menu items, like About xxx, Hide xxx, and Hide Others. To set the action of a menu item to a standard action, you should set the role attribute of the menu item. Main Menu’s Name​ On macOS the label of the application menu’s first item is always your app’s name, no matter what label you set. To change it, modify your app bundle’s Info.plist file. See About Information Property List Files for more information. Setting Menu for Specific Browser Window (Linux Windows)​ The setMenu method of browser windows can set the menu of certain browser windows. Menu Item Position​ You can make use of before, after, beforeGroupContaining, afterGroupContaining and id to control how the item will be placed when building a menu with Menu.buildFromTemplate. By default, items will be inserted in the order they exist in the template unless one of the specified positioning keywords is used. Examples​ Template: Menu: Template: Menu: Template: Menu:

Communicate asynchronously from the main process to renderer processes. Process: Main The ipcMain module is an Event Emitter. When used in the main process, it handles asynchronous and synchronous messages sent from a renderer process (web page). Messages sent from a renderer will be emitted to this module. For usage examples, check out the IPC tutorial. Sending messages​ It is also possible to send messages from the main process to the renderer process, see webContents.send for more information. Methods​ The ipcMain module has the following method to listen for events: ipcMain.on(channel, listener)​ Listens to channel, when a new message arrives listener would be called with listener(event, args…). ipcMain.once(channel, listener)​ Adds a one time listener function for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed. ipcMain.removeListener(channel, listener)​ Removes the specified listener from the listener array for the specified channel. ipcMain.removeAllListeners([channel])​ Removes listeners of the specified channel. ipcMain.handle(channel, listener)​ Adds a handler for an invokeable IPC. This handler will be called whenever a renderer calls ipcRenderer.invoke(channel, …args). If listener returns a Promise, the eventual result of the promise will be returned as a reply to the remote caller. Otherwise, the return value of the listener will be used as the value of the reply. Main Process Renderer Process The event that is passed as the first argument to the handler is the same as that passed to a regular event listener. It includes information about which WebContents is the source of the invoke request. Errors thrown through handle in the main process are not transparent as they are serialized and only the message property from the original error is provided to the renderer process. Please refer to #24427 for details. ipcMain.handleOnce(channel, listener)​ Handles a single invokeable IPC message, then removes the listener. See ipcMain.handle(channel, listener). ipcMain.removeHandler(channel)​ Removes any handler for channel, if present.

In-app purchases on Mac App Store. Process: Main Events​ The inAppPurchase module emits the following events: Event: ‘transactions-updated’​ Emitted when one or more transactions have been updated. Returns: Methods​ The inAppPurchase module has the following methods: inAppPurchase.purchaseProduct(productID[, opts])​ Returns Promise<boolean> – Returns true if the product is valid and added to the payment queue. You should listen for the transactions-updated event as soon as possible and certainly before you call purchaseProduct. inAppPurchase.getProducts(productIDs)​ Returns Promise<Product[]> – Resolves with an array of Product objects. Retrieves the product descriptions. inAppPurchase.canMakePayments()​ Returns boolean – whether a user can make a payment. inAppPurchase.restoreCompletedTransactions()​ Restores finished transactions. This method can be called either to install purchases on additional devices, or to restore purchases for an application that the user deleted and reinstalled. The payment queue delivers a new transaction for each previously completed transaction that can be restored. Each transaction includes a copy of the original transaction. inAppPurchase.getReceiptURL()​ Returns string – the path to the receipt. inAppPurchase.finishAllTransactions()​ Completes all pending transactions. inAppPurchase.finishTransactionByDate(date)​ Completes the pending transactions corresponding to the date.

Detect keyboard events when the application does not have keyboard focus. Process: Main The globalShortcut module can register/unregister a global keyboard shortcut with the operating system so that you can customize the operations for various shortcuts. Note: The shortcut is global; it will work even if the app does not have the keyboard focus. This module cannot be used before the ready event of the app module is emitted. Methods​ The globalShortcut module has the following methods: globalShortcut.register(accelerator, callback)​ Returns boolean – Whether or not the shortcut was registered successfully. Registers a global shortcut of accelerator. The callback is called when the registered shortcut is pressed by the user. When the accelerator is already taken by other applications, this call will silently fail. This behavior is intended by operating systems, since they don’t want applications to fight for global shortcuts. The following accelerators will not be registered successfully on macOS 10.14 Mojave unless the app has been authorized as a trusted accessibility client: globalShortcut.registerAll(accelerators, callback)​ Registers a global shortcut of all accelerator items in accelerators. The callback is called when any of the registered shortcuts are pressed by the user. When a given accelerator is already taken by other applications, this call will silently fail. This behavior is intended by operating systems, since they don’t want applications to fight for global shortcuts. The following accelerators will not be registered successfully on macOS 10.14 Mojave unless the app has been authorized as a trusted accessibility client: globalShortcut.isRegistered(accelerator)​ Returns boolean – Whether this application has registered accelerator. When the accelerator is already taken by other applications, this call will still return false. This behavior is intended by operating systems, since they don’t want applications to fight for global shortcuts. globalShortcut.unregister(accelerator)​ Unregisters the global shortcut of accelerator. globalShortcut.unregisterAll()​ Unregisters all of the global shortcuts.

Display native system dialogs for opening and saving files, alerting, etc. Process: Main An example of showing a dialog to select multiple files: Methods​ The dialog module has the following methods: dialog.showOpenDialogSync([browserWindow, ]options)​ Returns string[] | undefined, the file paths chosen by the user; if the dialog is cancelled it returns undefined. The browserWindow argument allows the dialog to attach itself to a parent window, making it modal. The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. For example: The extensions array should contain extensions without wildcards or dots (e.g. ‘png’ is good but ‘.png’ and ‘*.png’ are bad). To show all files, use the ‘*’ wildcard (no other wildcard is supported). Note: On Windows and Linux an open dialog can not be both a file selector and a directory selector, so if you set properties to [‘openFile’, ‘openDirectory’] on these platforms, a directory selector will be shown. dialog.showOpenDialog([browserWindow, ]options)​ Returns Promise<Object> – Resolve with an object containing the following: The browserWindow argument allows the dialog to attach itself to a parent window, making it modal. The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. For example: The extensions array should contain extensions without wildcards or dots (e.g. ‘png’ is good but ‘.png’ and ‘*.png’ are bad). To show all files, use the ‘*’ wildcard (no other wildcard is supported). Note: On Windows and Linux an open dialog can not be both a file selector and a directory selector, so if you set properties to [‘openFile’, ‘openDirectory’] on these platforms, a directory selector will be shown. dialog.showSaveDialogSync([browserWindow, ]options)​ Returns string, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string. The browserWindow argument allows the dialog to attach itself to a parent window, making it modal. The filters specifies an array of file types that can be displayed, see dialog.showOpenDialog for an example. dialog.showSaveDialog([browserWindow, ]options)​ Returns Promise<Object> – Resolve with an object containing the following: The browserWindow argument allows the dialog to attach itself to a parent window, making it modal. The filters specifies an array of file types that can be displayed, see dialog.showOpenDialog for an example. Note: On macOS, using the asynchronous version is recommended to avoid issues when expanding and collapsing the dialog. dialog.showMessageBoxSync([browserWindow, ]options)​ Returns Integer – the index of the clicked button. Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. The browserWindow argument allows the dialog to attach itself to a parent window, making it modal. If browserWindow is not shown dialog will not be attached to it. In such case it will be displayed as an independent window. dialog.showMessageBox([browserWindow, ]options)​ Returns Promise<Object> – resolves with a promise containing the following properties: Shows a message box. The browserWindow argument allows the dialog to attach itself to a parent window, making it modal. dialog.showErrorBox(title, content)​ Displays a modal dialog that shows an error message. This API can be called safely before the ready event the app module emits, it is usually used to report errors in early stage of startup. If called before the app readyevent on Linux, the message will be emitted to stderr, and no GUI dialog will appear. dialog.showCertificateTrustDialog([browserWindow, ]options) macOS Windows​ Returns Promise<void> – resolves when the certificate trust dialog is shown. On macOS, this displays a modal dialog that shows a message and certificate information, and gives the user the option of trusting/importing the certificate. If you provide a browserWindow argument the dialog will be attached to the parent window, making it modal. On Windows the options are more limited, due to the Win32 APIs used: Bookmarks array​ showOpenDialog, showOpenDialogSync, showSaveDialog, and showSaveDialogSync will return a bookmarks array. Build Type securityScopedBookmarks boolean Return Type Return Value macOS mas True Success [‘LONGBOOKMARKSTRING’] macOS mas True Error [”] (array of empty string) macOS mas False NA [] (empty array) non mas any NA [] (empty array) Sheets​ On macOS, dialogs are presented as sheets attached to a window if you provide a BrowserWindow reference in the browserWindow parameter, or modals if no window is provided. You can call BrowserWindow.getCurrentWindow().setSheetOffset(offset) to change the offset from the window frame where sheets are attached.

Access information about media sources that can be used to capture audio and video from the desktop using the navigator.mediaDevices.getUserMedia API. Process: Main The following example shows how to capture video from a desktop window whose title is Electron: See navigator.mediaDevices.getDisplayMedia for more information. Note: navigator.mediaDevices.getDisplayMedia does not permit the use of deviceId for selection of a source – see specification. Methods​ The desktopCapturer module has the following methods: desktopCapturer.getSources(options)​ Returns Promise<DesktopCapturerSource[]> – Resolves with an array of DesktopCapturerSource objects, each DesktopCapturerSource represents a screen or an individual window that can be captured. Note Capturing the screen contents requires user consent on macOS 10.15 Catalina or higher, which can detected by systemPreferences.getMediaAccessStatus. Caveats​ navigator.mediaDevices.getUserMedia does not work on macOS for audio capture due to a fundamental limitation whereby apps that want to access the system’s audio require a signed kernel extension. Chromium, and by extension Electron, does not provide this. It is possible to circumvent this limitation by capturing system audio with another macOS app like Soundflower and passing it through a virtual audio input device. This virtual device can then be queried with navigator.mediaDevices.getUserMedia.

Submit crash reports to a remote server. Process: Main, Renderer The following is an example of setting up Electron to automatically submit crash reports to a remote server: For setting up a server to accept and process crash reports, you can use following projects: Note: Electron uses Crashpad, not Breakpad, to collect and upload crashes, but for the time being, the upload protocol is the same. Or use a 3rd party hosted solution: Crash reports are stored temporarily before being uploaded in a directory underneath the app’s user data directory, called ‘Crashpad’. You can override this directory by calling app.setPath(‘crashDumps’, ‘/path/to/crashes’) before starting the crash reporter. Electron uses crashpad to monitor and report crashes. Methods​ The crashReporter module has the following methods: crashReporter.start(options)​ This method must be called before using any other crashReporter APIs. Once initialized this way, the crashpad handler collects crashes from all subsequently created processes. The crash reporter cannot be disabled once started. This method should be called as early as possible in app startup, preferably before app.on(‘ready’). If the crash reporter is not initialized at the time a renderer process is created, then that renderer process will not be monitored by the crash reporter. Note: You can test out the crash reporter by generating a crash using process.crash(). Note: If you need to send additional/updated extra parameters after your first call start you can call addExtraParameter. Note: Parameters passed in extra, globalExtra or set with addExtraParameter have limits on the length of the keys and values. Key names must be at most 39 bytes long, and values must be no longer than 127 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated. Note: This method is only available in the main process. crashReporter.getLastCrashReport()​ Returns CrashReport | null – The date and ID of the last crash report. Only crash reports that have been uploaded will be returned; even if a crash report is present on disk it will not be returned until it is uploaded. In the case that there are no uploaded reports, null is returned. Note: This method is only available in the main process. crashReporter.getUploadedReports()​ Returns CrashReport[]: Returns all uploaded crash reports. Each report contains the date and uploaded ID. Note: This method is only available in the main process. crashReporter.getUploadToServer()​ Returns boolean – Whether reports should be submitted to the server. Set through the start method or setUploadToServer. Note: This method is only available in the main process. crashReporter.setUploadToServer(uploadToServer)​ This would normally be controlled by user preferences. This has no effect if called before start is called. Note: This method is only available in the main process. crashReporter.addExtraParameter(key, value)​ Set an extra parameter to be sent with the crash report. The values specified here will be sent in addition to any values set via the extra option when start was called. Parameters added in this fashion (or via the extra parameter to crashReporter.start) are specific to the calling process. Adding extra parameters in the main process will not cause those parameters to be sent along with crashes from renderer or other child processes. Similarly, adding extra parameters in a renderer process will not result in those parameters being sent with crashes that occur in other renderer processes or in the main process. Note: Parameters have limits on the length of the keys and values. Key names must be no longer than 39 bytes, and values must be no longer than 20320 bytes. Keys with names longer than the maximum will be silently ignored. Key values longer than the maximum length will be truncated. crashReporter.removeExtraParameter(key)​ Remove an extra parameter from the current set of parameters. Future crashes will not include this parameter. crashReporter.getParameters()​ Returns Record<string, string> – The current ‘extra’ parameters of the crash reporter. In Node child processes​ Since require(‘electron’) is not available in Node child processes, the following APIs are available on the process object in Node child processes. process.crashReporter.start(options)​ See crashReporter.start(). Note that if the crash reporter is started in the main process, it will automatically monitor child processes, so it should not be started in the child process. Only use this method if the main process does not initialize the crash reporter. process.crashReporter.getParameters()​ See crashReporter.getParameters(). process.crashReporter.addExtraParameter(key, value)​ See crashReporter.addExtraParameter(key, value). process.crashReporter.removeExtraParameter(key)​ See crashReporter.removeExtraParameter(key). Crash Report Payload​ The crash reporter will send the following data to the submitURL as a multipart/form-data POST: