System Tray Icon API for WebviewJS Applications

The system tray API lets you embed a persistent icon in the operating system’s notification area (macOS menu bar, Windows system tray, or Linux status area). Tray icons can carry context menus, tooltips, titles, and respond to pointer events — making them ideal for background applications, status indicators, and quick-access launchers. Tray icons must be created via app.createTrayIcon() so that construction always happens on the native event-loop thread.

Keep a strong JavaScript reference to the TrayIcon object for as long as you need its methods or event listeners. If the wrapper is garbage-collected, you lose the ability to update or listen to the icon. The native icon itself is owned by the Application and will be removed when app.exit() is called even if the JS wrapper is still reachable.

Creating a Tray Icon

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

const app = new Application();

// Build a 16×16 solid-blue RGBA icon
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)
}

await app.whenReady();

const 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' },
    ],
  },
});

Icon data may be raw RGBA bytes paired with explicit width and height dimensions, or an encoded image file (PNG, JPEG, ICO, etc.) supplied without dimensions. The library detects the format automatically.

`app.createTrayIcon(options)`

options

TrayIconOptions

required

Configuration object for the new tray icon.

Show TrayIconOptions fields

string

Optional stable identifier for this icon. Automatically generated when omitted. Accessible later via tray.id.

icon

TrayIconImage

Initial icon image. Omit to create a tray entry with no visible icon.

Show TrayIconImage fields

data

Buffer

required

Raw image bytes. Pass raw RGBA pixels together with width and height, or an encoded image buffer (PNG, JPEG, ICO, BMP, WebP, etc.) without dimensions.

width

number

Image width in pixels. Required when data contains raw RGBA bytes; omit for encoded formats.

height

number

Image height in pixels. Required when data contains raw RGBA bytes; omit for encoded formats.

Tooltip text shown on hover. Not supported on Linux.

title

string

Text label rendered next to the icon in the menu bar. macOS and Linux only — ignored on Windows.

Context menu attached to the icon. See the Menu API for the full MenuOptions shape.

iconIsTemplate

boolean

When true, the icon is treated as a macOS template image (monochrome, automatically adapted for light/dark appearances). macOS only.

Open the context menu on a left-click. Defaults to platform convention. Not supported on Linux.

Open the context menu on a right-click. Defaults to platform convention. Not supported on Linux.

returns

TrayIcon

A TrayIcon instance that implements TypedEventEmitter<TrayEventMap> and Symbol.dispose.

Properties

string

Read-only string identifier for the icon. Matches the id provided in TrayIconOptions, or an auto-generated value when none was given.

Methods

`setIcon(icon, width?, height?)`

icon

Uint8Array | number[]

required

New icon image data — either raw RGBA bytes (with dimensions) or an encoded image buffer.

width

number

Width in pixels. Required for raw RGBA data.

height

number

Height in pixels. Required for raw RGBA data.

Replaces the current icon image.

`removeIcon()`

Hides the icon graphic, leaving the tray entry otherwise intact. Call setIcon() to restore it.

New menu configuration. Pass null or undefined to detach the menu entirely.

Replaces the attached context menu at runtime.

New tooltip string. Pass null or undefined to remove the tooltip.

Tooltip is not supported on Linux.

`setTitle(title?)`

title

string | null | undefined

Label text to display beside the icon. Pass null or undefined to remove it.

Title is not supported on Windows.

`setVisible(visible)`

visible

boolean

required

true to show the icon, false to hide it.

Shows or hides the tray icon without disposing it.

`setIconAsTemplate(value)`

value

boolean

required

true to enable template-image rendering, false to disable it.

Toggles macOS template-image mode for automatic light/dark adaptation.

This method is macOS-only and has no effect on other platforms.

`setShowMenuOnLeftClick(value)`

value

boolean

required

Whether to open the context menu on a left-click event.

Not supported on Linux.

`setShowMenuOnRightClick(value)`

value

boolean

required

Whether to open the context menu on a right-click event.

Not supported on Linux.

`showMenu()`

Programmatically opens the attached context menu, as if the user had clicked the icon. Useful for triggering the menu from application logic rather than user interaction.

`rect()`

Returns the bounding rectangle of the tray icon in screen coordinates, or null when the icon is hidden or the platform cannot report its position.

returns

TrayRect | null

Show TrayRect fields

number

Left edge of the icon in physical screen pixels.

number

Top edge of the icon in physical screen pixels.

width

number

Width of the icon area in physical pixels.

height

number

Height of the icon area in physical pixels.

`dispose()`

Immediately removes the tray icon and releases native resources. After calling dispose(), all method calls on the instance will throw. Equivalent to the Symbol.dispose protocol for use with using.

`isDisposed()`

returns

boolean

true after dispose() has been called or app.exit() has removed the icon.

Events

TrayIcon implements TypedEventEmitter<TrayEventMap>. Use .on(), .once(), .off(), and the other standard EventEmitter methods to subscribe.

Linux does not emit pointer events (click, double-click, enter, move, leave). Tray menu selections on all platforms are reported via the application-level custom-menu-click event, not through the tray emitter.

Event	Payload	Notes
`click`	`TrayEventPayload`	Single click on the icon
`double-click`	`TrayEventPayload`	Double click on the icon
`enter`	`TrayEventPayload`	Cursor entered the icon area
`move`	`TrayEventPayload`	Cursor moved within the icon area
`leave`	`TrayEventPayload`	Cursor left the icon area

`TrayEventPayload`

event

string

Name of the event (e.g. "click", "double-click").

string

The id of the TrayIcon that fired the event.

number

Horizontal cursor position in physical screen pixels.

number

Vertical cursor position in physical screen pixels.

rect

TrayRect

Bounding rectangle of the tray icon at the time of the event.

button

string | undefined

Mouse button involved ("left", "right", "middle"). Present on click events.

buttonState

string | undefined

State of the button ("pressed", "released"). Present on click events.

Platform Notes

macOS

The menu bar is shared across all applications; tray entries appear on the right side.
setTitle() is supported and renders inline text next to the icon.
setIconAsTemplate(true) enables automatic monochrome adaptation for light/dark modes.
Both left- and right-click menu triggers are configurable.

Windows

Icons appear in the notification area (bottom-right system tray).
setTitle() has no effect on Windows.
Tooltip and click-menu configuration are supported.
Use a 16×16 or 32×32 pixel icon for best results.

Linux

Tray support depends on the desktop environment and any installed system-tray extension.
Pointer events (click, double-click, enter, move, leave) are not emitted.
Tooltip and click-menu configuration are not supported.
GTK status-icon or AppIndicator backends are used depending on the build.

Full Example

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

const app = new Application();

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

const window = app.createBrowserWindow({ title: 'Tray Example' });
window.createWebview({ html: '<h1>WebviewJS tray example</h1>' });

// Tray must be created after the app is ready
await app.whenReady();

const tray = app.createTrayIcon({
  id: 'example',
  icon: { data: rgba, width: size, height: size },
  tooltip: 'WebviewJS tray example',
  menu: {
    items: [
      { id: 'show', label: 'Show window' },
      { role: 'separator' },
      { id: 'quit', label: 'Quit' },
    ],
  },
});

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

// Menu item selections come through the application event
app.on('custom-menu-click', ({ customMenuEvent }) => {
  if (customMenuEvent.id === 'show') window.show();
  if (customMenuEvent.id === 'quit') app.exit();
});

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

To change the icon dynamically (e.g., to indicate a status change), call tray.setIcon() with new RGBA data at any time after creation.

Core

UI & Notifications

Reference

System Tray Icon API for WebviewJS Applications

Creating a Tray Icon

`app.createTrayIcon(options)`

Properties

Methods

`setIcon(icon, width?, height?)`

`removeIcon()`

`setMenu(menu?)`

`setTooltip(tooltip?)`

`setTitle(title?)`

`setVisible(visible)`

`setIconAsTemplate(value)`

`setShowMenuOnLeftClick(value)`

`setShowMenuOnRightClick(value)`

`showMenu()`

`rect()`

`dispose()`

`isDisposed()`

Events

`TrayEventPayload`

Platform Notes

Full Example

Build docs developers (and LLMs) love

Core

UI & Notifications

Reference

Documentation Index

​Creating a Tray Icon

​app.createTrayIcon(options)

​Properties

​Methods

​setIcon(icon, width?, height?)

​removeIcon()

​setMenu(menu?)

​setTooltip(tooltip?)

​setTitle(title?)

​setVisible(visible)

​setIconAsTemplate(value)

​setShowMenuOnLeftClick(value)

​setShowMenuOnRightClick(value)

​showMenu()

​rect()

​dispose()

​isDisposed()

​Events

​TrayEventPayload

​Platform Notes

​Full Example

Build docs developers (and LLMs) love

Creating a Tray Icon

`app.createTrayIcon(options)`

Properties

Methods

`setIcon(icon, width?, height?)`

`removeIcon()`

`setMenu(menu?)`

`setTooltip(tooltip?)`

`setTitle(title?)`

`setVisible(visible)`

`setIconAsTemplate(value)`

`setShowMenuOnLeftClick(value)`

`setShowMenuOnRightClick(value)`

`showMenu()`

`rect()`

`dispose()`

`isDisposed()`

Events

`TrayEventPayload`

Platform Notes

Full Example