Tray

Create and manage system tray icon and menu.

import {Tray} from "electrobun/bun";

const tray = new Tray({
  title: "Example Tray Item (click to create menu)",
  // This can be a views url or an absolute file path
  image: "views://assets/electrobun-logo-32-template.png",
  template: true,
  width: 32,
  height: 32,
});

// map action names to clicked state
// Note: This is just used for this example
const menuState = {
  "item-1": false,
  "sub-item-1": false,
  "sub-item-2": true,
};

const updateTrayMenu = () => {
  tray.setMenu([
    {
      type: "normal",
      label: "Toggle me",
      action: "item-1",
      checked: menuState["item-1"],
      tooltip: "I'm a tooltip",
      submenu: [
        {
          type: "normal",
          label: "Click me to toggle sub-item 2",
          tooltip: "i will also unhide sub-item-3",
          action: "sub-item-1",
        },
        {
          type: "divider",
        },
        {
          type: "normal",
          label: "Toggle sub-item-3's visibility",
          action: "sub-item-2",
          enabled: menuState["sub-item-1"],
        },
        {
          type: "normal",
          label: "I was hidden",
          action: "sub-item-3",
          hidden: menuState["sub-item-2"],
        },
      ],
    },
  ]);
};

// TODO: events should be typed
tray.on("tray-clicked", (e) => {
  const { id, action } = e.data as { id: number; action: string };

  if (action === "") {
    // main menu was clicked before we create a system tray menu for it.
    updateTrayMenu();
    tray.setTitle("Example Tray Item (click to open menu)");
  } else {
    // once there's a menu, we can toggle the state of the menu items
    menuState[action] = !menuState[action];
    updateTrayMenu();
  }
  // respond to left and right clicks on the tray icon/name
  console.log("event listener for tray clicked", e.data.action);
});

Constructor Options

title

This is the text that will appear in your system tray

image

This is an optional url to an image to load. You can use the views:// schema to access local bundled images.

template

You can use a full-color image like a png but that image will just be shown as is. On MacOS you can create a template image and set the template property to true. A template image uses opacity to define a black and white image that adapts to your systems light/dark mode.

width and height

Set the dimensions of the image used in the system tray

Methods

setMenu

Call setMenu whenever you want to show the menu. Typically you would listen for the tray-clicked event, then show the menu and listen for the tray-item-clicked. Your app could also listen for keyboard shortcuts or show the system tray menu in response to something else.

A common pattern is to create a function that dynamically generates the menu from some kind of state to implement things like checkbox toggles.

setTitle

Update the text displayed in the system tray.

tray.setTitle("New Status");

setImage

Update the tray icon image. Accepts a views:// URL or an absolute file path.

tray.setImage("views://assets/new-icon-32-template.png");

setVisible

Show or hide the tray icon. When hidden, the tray is removed from the system tray. When shown again, it is recreated.

// Hide the tray icon
tray.setVisible(false);

// Show it again
tray.setVisible(true);

getBounds

Get the bounding rectangle of the tray icon. Returns an object with x, y, width, and height properties.

const bounds = tray.getBounds();
console.log(`Tray icon at (${bounds.x}, ${bounds.y}) size ${bounds.width}x${bounds.height}`);

remove

Permanently remove the tray icon from the system tray.

tray.remove();

Menu Items

See Application Menu for more info on available properties for menu items.

Events

tray-clicked

Fired when the system tray icon is clicked, or when a menu item is clicked. The event data includes an action property — it will be an empty string when the tray icon itself is clicked, or the action name of the menu item that was clicked.

tray.on("tray-clicked", (e) => {
  const { id, action } = e.data;

  if (action === "") {
    // Tray icon was clicked (no menu item)
    console.log("Tray icon clicked");
  } else {
    // A menu item was clicked
    console.log("Menu item clicked:", action);
  }
});