Tray

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

Overview

The Electron.Tray API provides the ability to add icons and context menus to the system's notification area (system tray). This allows applications to provide quick access to common functions and maintain a presence in the system even when windows are closed.

Key Methods

Tray Creation and Management

Show(string, MenuItem)

Parameters:

• image - The image to use for the tray icon
• menuItem - Single menu item for the tray context menu

Description: Shows the tray icon with a single menu item.

Show(string, MenuItem[])

Parameters:

• image - The image to use for the tray icon
• menuItems - Array of menu items for the tray context menu

Description: Shows the tray icon with multiple menu items.

Show(string)

Parameters:

• image - The image to use for the tray icon

Description: Shows the tray icon without a context menu.

Destroy()

Description: Destroys the tray icon immediately.

IsDestroyedAsync()

Returns: Whether the tray icon is destroyed.

Description: Check if the tray icon has been destroyed.

Tray Appearance

SetImage(string)

Parameters:

• image - New image for the tray icon

Description: Sets the image associated with this tray icon.

SetPressedImage(string)

Parameters:

• image - Image for pressed state

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

SetToolTip(string)

Parameters:

• toolTip - Tooltip text

Description: Sets the hover text for this tray icon.

SetTitle(string)

Parameters:

• title - Title text

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

Windows-Specific Features

DisplayBalloon(DisplayBalloonOptions)

Parameters:

• options - Balloon notification options

Description: Windows: Displays a tray balloon notification.

Events

OnClick

Description: Emitted when the tray icon is clicked.

OnRightClick

Description: macOS, Windows: Emitted when the tray icon is right clicked.

OnDoubleClick

Description: macOS, Windows: Emitted when the tray icon is double clicked.

OnBalloonShow

Description: Windows: Emitted when the tray balloon shows.

OnBalloonClick

Description: Windows: Emitted when the tray balloon is clicked.

OnBalloonClosed

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

Properties

MenuItems

Type: IReadOnlyCollection

Description: Gets a read-only collection of all current tray menu items.

Usage Examples

Basic Tray Icon

// Simple tray icon
await Electron.Tray.Show("assets/tray-icon.png");

// Tray icon with single menu item
await Electron.Tray.Show("assets/tray-icon.png", new MenuItem
{
    Label = "Show Window",
    Click = () => ShowMainWindow()
});

Tray with Context Menu

// Tray with multiple menu items
var trayMenuItems = new[]
{
    new MenuItem { Label = "Show Window", Click = () => ShowMainWindow() },
    new MenuItem { Label = "Settings", Click = () => OpenSettings() },
    new MenuItem { Type = MenuType.Separator },
    new MenuItem { Label = "Exit", Click = () => Electron.App.Quit() }
};

await Electron.Tray.Show("assets/tray-icon.png", trayMenuItems);

Dynamic Tray Updates

// Update tray tooltip based on status
await Electron.Tray.SetToolTip("MyApp - Connected");

// Change tray icon based on state
if (isConnected)
{
    await Electron.Tray.SetImage("assets/connected.png");
}
else
{
    await Electron.Tray.SetImage("assets/disconnected.png");
}

Tray Event Handling

// Handle tray clicks
Electron.Tray.OnClick += (clickArgs, bounds) =>
{
    if (clickArgs.AltKey || clickArgs.ShiftKey)
    {
        // Alt+Click or Shift+Click - show context menu
        Electron.Menu.ContextMenuPopup(Electron.WindowManager.BrowserWindows.First());
    }
    else
    {
        // Regular click - toggle main window
        ToggleMainWindow();
    }
};

Electron.Tray.OnRightClick += (clickArgs, bounds) =>
{
    // Show context menu on right click
    Electron.Menu.ContextMenuPopup(Electron.WindowManager.BrowserWindows.First());
};

Windows Balloon Notifications

// Show Windows balloon notification
await Electron.Tray.DisplayBalloon(new DisplayBalloonOptions
{
    Title = "Background Task Complete",
    Content = "Your file has been processed successfully.",
    Icon = "assets/notification-icon.ico"
});

// Handle balloon events
Electron.Tray.OnBalloonClick += () =>
{
    ShowMainWindow();
    Electron.WindowManager.BrowserWindows.First().Focus();
};

macOS Tray Features

// macOS specific tray features
if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
{
    await Electron.Tray.SetTitle("MyApp");

    // Use template image for dark mode support
    await Electron.Tray.SetImage("assets/tray-template.png");
    await Electron.Tray.SetPressedImage("assets/tray-pressed-template.png");
}

Application Integration

// Integrate with application lifecycle
Electron.App.WindowAllClosed += () =>
{
    // Keep app running in tray when windows are closed
    if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
    {
        Electron.App.Hide();
    }
};

// Handle tray double-click
Electron.Tray.OnDoubleClick += (clickArgs, bounds) =>
{
    ShowMainWindow();
    Electron.WindowManager.BrowserWindows.First().Focus();
};

Related APIs

• Electron.Menu - Context menus for tray icons
• Electron.Notification - Desktop notifications
• Electron.App - Application lifecycle events
• Electron.WindowManager - Windows to show/hide from tray

Additional Resources

• Electron Tray Documentation - Official Electron tray API