electron/docs/api/tray.md

Tray

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

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

let appIcon = null;
app.on('ready', () => {
  appIcon = 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'}
  ]);
  appIcon.setToolTip('This is my application.');
  appIcon.setContextMenu(contextMenu);
});

Platform limitations:

• On Linux the app indicator will be used if it is supported, otherwise GtkStatusIcon will be used instead.
• On Linux distributions that only have app indicator support, you have to install libappindicator1 to make the tray icon work.
• App indicator will only be shown when it has a context menu.
• When app indicator is used on Linux, the click event is ignored.
• On Linux in order for changes made to individual MenuItems to take effect, you have to call setContextMenu again. For example:

contextMenu.items[2].checked = false;
appIcon.setContextMenu(contextMenu);

• On Windows it is recommended to use ICO icons to get best visual effects.

If you want to keep exact same behaviors on all platforms, you should not rely on the click event and always attach a context menu to the tray icon.

Class: Tray

Tray is an EventEmitter.

new Tray(image)

• image NativeImage

Creates a new tray icon associated with the image.

Events

The Tray module emits the following events:

Note: Some events are only available on specific operating systems and are labeled as such.

Event: 'click'

• event Event
  • altKey Boolean
  • shiftKey Boolean
  • ctrlKey Boolean
  • metaKey Boolean
• bounds Object - the bounds of tray icon.
  • x Integer
  • y Integer
  • width Integer
  • height Integer

Emitted when the tray icon is clicked.

Note: The bounds payload is only implemented on macOS and Windows.

Event: 'right-click' macOS Windows

• event Event
  • altKey Boolean
  • shiftKey Boolean
  • ctrlKey Boolean
  • metaKey Boolean
• bounds Object - the bounds of tray icon.
  • x Integer
  • y Integer
  • width Integer
  • height Integer

Emitted when the tray icon is right clicked.

Event: 'double-click' macOS Windows

• event Event
  • altKey Boolean
  • shiftKey Boolean
  • ctrlKey Boolean
  • metaKey Boolean
• bounds Object - the bounds of tray icon
  • x Integer
  • y Integer
  • width Integer
  • height Integer

Emitted when the tray icon is double 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

• event
• files Array - the file path of dropped files.

Emitted when dragged files are 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.

Methods

The Tray module has the following methods:

Note: Some methods are only available on specific operating systems and are labeled as such.

Tray.destroy()

Destroys the tray icon immediately.

Tray.setImage(image)

• image NativeImage

Sets the image associated with this tray icon.

Tray.setPressedImage(image) macOS

• image NativeImage

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

• title String

Sets the title displayed aside of the tray icon in the status bar.

Tray.setHighlightMode(highlight) macOS

• highlight Boolean

Sets whether the tray icon's background becomes highlighted (in blue) when the tray icon is clicked. Defaults to true.

Tray.displayBalloon(options) Windows

• options Object
  • icon NativeImage
  • title String
  • content String

Displays a tray balloon.

Tray.popUpContextMenu([menu, position]) macOS Windows

• menu Menu (optional)
• position Object (optional) - The pop up position.
  • x Integer
  • y Integer

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.setContextMenu(menu)

• menu Menu

Sets the context menu for this icon.