TrayIcon API — System Tray Icons, Menus, and Events

A system tray icon lets your application remain available in the operating system’s notification area while the application is alive, even when no visible window is open. You create tray icons through app.createTrayIcon(), which registers the native resource with the application.

Tray icons are supported on Windows, macOS, and Linux. The Android backend explicitly rejects tray creation, and the published FreeBSD target is a GUI stub.

Creating a tray icon

Call app.createTrayIcon(TrayIconOptions) through the application. A readiness check is not required; you can create the icon before or after starting the event pump.

import { Application } from '@webviewjs/webview';

const app = new Application();

// Build a 16×16 solid-blue RGBA icon in memory
const size = 16;
const rgba = Buffer.alloc(size * size * 4);
for (let i = 0; i < rgba.length; i += 4) {
  rgba[i]     = 70;   // R
  rgba[i + 1] = 150;  // G
  rgba[i + 2] = 240;  // B
  rgba[i + 3] = 255;  // A (fully opaque)
}

let tray;

app.whenReady().then(() => {
  tray = app.createTrayIcon({
    id: 'main',
    icon: { data: rgba, width: size, height: size },
    tooltip: 'My Application',
    menu: {
      items: [
        { id: 'show', label: 'Show window' },
        { role: 'separator' },
        { id: 'quit', label: 'Quit' },
      ],
    },
  });

  tray.on('click', ({ button, buttonState }) => {
    console.log('Tray clicked:', button, buttonState);
  });
});

// Handle tray menu selections
app.on('custom-menu-click', ({ customMenuEvent }) => {
  if (customMenuEvent.id === 'show') win.show();
  if (customMenuEvent.id === 'quit') app.exit();
});

const win = app.createBrowserWindow({ title: 'Tray Example' });
win.createWebview({ html: '<h1>Running in the tray</h1>' });

app.on('application-close-requested', () => app.exit());
app.run();

TrayIconOptions

Pass a TrayIconOptions object to app.createTrayIcon().

interface TrayIconOptions {
  id?:               string;
  icon?:             TrayIconImage;
  tooltip?:          string;
  title?:            string;
  menu?:             MenuOptions;
  iconIsTemplate?:   boolean;
  menuOnLeftClick?:  boolean;
  menuOnRightClick?: boolean;
}

interface TrayIconImage {
  data:    Buffer;
  width?:  number;
  height?: number;
}

Field	Type	Description
`id`	`string`	Optional unique identifier for this tray icon. Auto-generated if omitted.
`icon`	`TrayIconImage`	The icon to display. See below for raw RGBA vs encoded image formats.
`tooltip`	`string`	Text shown when the user hovers over the tray icon. Not supported on Linux.
`title`	`string`	Text displayed next to the icon. Supported on macOS and Linux when the tray backend displays labels; unsupported on Windows.
`menu`	`MenuOptions`	Context menu shown when the user right-clicks the icon (or left-clicks, if `menuOnLeftClick` is set).
`iconIsTemplate`	`boolean`	Treat the icon as a monochrome template that adapts to dark/light mode. macOS only.
`menuOnLeftClick`	`boolean`	Show the context menu on a left-click. Not supported on Linux.
`menuOnRightClick`	`boolean`	Show the context menu on a right-click (default platform behaviour on most systems). Not supported on Linux.

Icon data formats

The icon.data field accepts raw pixels or encoded image bytes:

Raw RGBA bytes — supply width and optionally height alongside a Buffer. The byte length must equal width × height × 4; if height is omitted, the icon is treated as square. Each pixel is four bytes: R, G, B, A.
Encoded image bytes — supply a Buffer containing a PNG, JPEG, WebP, GIF, BMP, ICO, or TIFF file without width or height. The native backend decodes the image automatically.

Providing height without width is invalid.

On Linux, the tray backend may not show an icon unless a menu is set. The title may also be hidden by the panel or tray implementation even when it is configured.

Methods

Once you have a TrayIcon instance returned by app.createTrayIcon(), you can call these methods at any time before the icon is disposed.

`tray.id`

tray.id: string

Read-only string identifier set at creation time (or auto-generated).

`tray.setIcon(data, width?, height?)`

tray.setIcon(data: Uint8Array | number[], width?: number, height?: number): void

Replace the tray icon image at runtime. Supply raw RGBA data with width and optionally height (a missing height means a square icon), or encoded image bytes without dimensions. Providing height without width is invalid.

`tray.removeIcon()`

tray.removeIcon(): void

Remove and hide the icon from the tray area. The TrayIcon instance remains valid; restore it by calling setIcon() with image data again.

tray.setMenu(menu?: MenuOptions | null): void

Set or replace the context menu. Pass undefined or null to remove it where the platform supports removal. On Linux, once a menu has been set, the native tray backend does not remove or replace it through this API, so configure the initial menu before creating the tray icon.

tray.setTooltip(tooltip?: string | null): void

Update the hover tooltip text. Not supported on Linux.

`tray.setTitle(title?)`

tray.setTitle(title?: string | null): void

Set or clear the text label shown next to the icon. macOS supports it, and Linux can display it when an icon is also present; Windows does not support it.

`tray.setVisible(visible)`

tray.setVisible(visible: boolean): void

Show or hide the tray icon without removing it. Hidden icons retain their configuration and can be made visible again.

`tray.setIconAsTemplate(value)`

tray.setIconAsTemplate(value: boolean): void

Mark the icon as a monochrome template image. When true, macOS renders the icon using the appropriate foreground colour for the current menu-bar appearance (dark or light). macOS only.

`tray.setShowMenuOnLeftClick(value)`

tray.setShowMenuOnLeftClick(value: boolean): void

Control whether a left-click opens the context menu. Not supported on Linux.

`tray.setShowMenuOnRightClick(value)`

tray.setShowMenuOnRightClick(value: boolean): void

Control whether a right-click opens the context menu. Not supported on Linux.

`tray.showMenu()`

tray.showMenu(): void

Programmatically open the tray context menu from your Node.js code on Windows and macOS. The Linux tray backend does not support this operation.

`tray.rect()`

tray.rect(): TrayRect | null

Return the bounding rectangle of the tray icon on screen, or null if the platform does not expose it.

interface TrayRect {
  x:      number;
  y:      number;
  width:  number;
  height: number;
}

Tray events

TrayIcon is a Node.js EventEmitter. Register listeners with tray.on(event, handler).

Event	Payload fields	Description
`click`	`id`, `x`, `y`, `rect`, `button?`, `buttonState?`	Fired when the user clicks the icon.
`double-click`	`id`, `x`, `y`, `rect`, `button?`, `buttonState?`	Fired on a double-click.
`enter`	`id`, `x`, `y`, `rect`	Cursor entered the icon’s bounding rectangle.
`move`	`id`, `x`, `y`, `rect`	Cursor is moving over the icon.
`leave`	`id`, `x`, `y`, `rect`	Cursor left the icon’s bounding rectangle.

interface TrayEventPayload {
  event:        string;
  id:           string;
  x:            number;
  y:            number;
  rect:         TrayRect;
  button?:      string;
  buttonState?: string;
}

tray.on('click', ({ button, buttonState, x, y }) => {
  console.log(`Tray icon clicked at (${x}, ${y}) — button: ${button}, state: ${buttonState}`);
});

tray.on('enter', () => console.log('Cursor entered tray icon'));
tray.on('leave', () => console.log('Cursor left tray icon'));

Clicking a menu item in the tray’s context menu does not fire a tray event. Instead, it fires the custom-menu-click event on the app instance, exactly the same as window menu clicks. Use customMenuEvent.id to identify which item was selected.

app.on('custom-menu-click', ({ customMenuEvent }) => {
  switch (customMenuEvent.id) {
    case 'show': win.show();   break;
    case 'quit': app.exit();  break;
  }
});

See the Menu — Handling menu clicks section for full details.

Platform notes

Feature	Windows	macOS	Linux
`title` (text next to icon)	✗ Not supported	✓ Supported	✓ Supported when an icon is present
`tooltip`	✓ Supported	✓ Supported	✗ Not supported
`menuOnLeftClick` / `menuOnRightClick`	✓ Supported	✓ Supported	✗ Not supported
Template icons (`setIconAsTemplate`)	✗ Not supported	✓ Supported	✗ Not supported
Pointer events (`click`, `enter`, etc.)	✓ Emitted	✓ Emitted	✗ Not emitted

Disposal

Call tray.dispose() to remove the icon from the system tray immediately. You can also use the ECMAScript explicit resource management syntax with Symbol.dispose.

// Explicit disposal
tray.dispose();

// Or using `using` (Node.js 24+ / TypeScript 5.2+)
{
  using tray = app.createTrayIcon({ /* … */ });
  // tray is automatically disposed when the block exits
}

Check whether an icon has already been disposed:

if (!tray.isDisposed()) {
  tray.setTooltip('Still alive');
}

When app.exit() is called, the Application object removes all tray icons it owns, regardless of whether the TrayIcon wrapper object is still reachable in your code. You do not need to call tray.dispose() before app.exit().

Core

UI & System

Types

TrayIcon API — System Tray Icons, Menus, and Events

Creating a tray icon

TrayIconOptions

Icon data formats

Methods

`tray.id`

`tray.setIcon(data, width?, height?)`

`tray.removeIcon()`

`tray.setMenu(menu?)`

`tray.setTooltip(tooltip?)`

`tray.setTitle(title?)`

`tray.setVisible(visible)`

`tray.setIconAsTemplate(value)`

`tray.setShowMenuOnLeftClick(value)`

`tray.setShowMenuOnRightClick(value)`

`tray.showMenu()`

`tray.rect()`

Tray events

Menu click events

Platform notes

Disposal

​Creating a tray icon

​TrayIconOptions

​Icon data formats

​Methods

​tray.id

​tray.setIcon(data, width?, height?)

​tray.removeIcon()

​tray.setMenu(menu?)

​tray.setTooltip(tooltip?)

​tray.setTitle(title?)

​tray.setVisible(visible)

​tray.setIconAsTemplate(value)

​tray.setShowMenuOnLeftClick(value)

​tray.setShowMenuOnRightClick(value)

​tray.showMenu()

​tray.rect()

​Tray events

​Menu click events

​Platform notes

​Disposal

Creating a tray icon

TrayIconOptions

Icon data formats

Methods

`tray.id`

`tray.setIcon(data, width?, height?)`

`tray.removeIcon()`

`tray.setMenu(menu?)`

`tray.setTooltip(tooltip?)`

`tray.setTitle(title?)`

`tray.setVisible(visible)`

`tray.setIconAsTemplate(value)`

`tray.setShowMenuOnLeftClick(value)`

`tray.setShowMenuOnRightClick(value)`

`tray.showMenu()`

`tray.rect()`

Tray events

Menu click events

Platform notes

Disposal