Tray Icon

A tray icon lives in the macOS menu bar, the Windows notification area, or a Linux StatusNotifierItem host. Put the artwork in resources/ and create the icon after startup. This is separate from the packaged App Icon.

#Create a tray icon

Ship a small PNG with the app, then create the icon from its packaged path:

native.App.GetPaths(func(paths *native.AppPaths, err error) {
	if err != nil || paths == nil {
		return
	}
	icon := filepath.Join(paths.ResourceDir, "trayTemplate.png")
	native.Tray.Create(native.TrayIconOptions{
		Icon:    native.TemplateImage(icon),
		Tooltip: "My App",
		Menu: []native.TrayMenuItem{
			{Label: "Show window", Click: showWindow},
			{Type: "separator"},
			{Label: "Quit", Click: func() { native.App.Quit(false, nil) }},
		},
	}, func(tray *native.TrayIcon, err error) {
		if err != nil {
			return
		}
		tray.OnEvent(func(event native.TrayEvent) {
			if event.Kind == "click" {
				showWindow()
			}
		})
	})
})

Tray.Create assigns an id. Call tray.Update, tray.ShowMenu, or tray.Destroy on that handle. native.Tray is supported on macOS, Windows, and Linux.

A 22×22 PNG is a good 1× source. Draw a 44×44 companion as trayTemplate@2x.png when you want a retina menu-bar image.

#Template images

On macOS, a template image is a monochrome mask. AppKit recolors it for the menu bar's light, dark, and highlighted appearances using only the alpha channel.

A filename whose stem ends in Template, optionally followed by @2x or @3x, is treated as a template:

resources/trayTemplate.png
resources/trayTemplate@2x.png

trayTemplate.png and statusTemplate@2x.png match. emailTemplateIcon.png does not.

Use native.TemplateImage(path) or set ImageSource.Template when the name does not follow that convention, or to force the flag off:

disabled := false
native.Desktop.SetDockIcon(&native.ImageSource{Path: iconPath, Template: &disabled})

The same ImageSource field applies to window icons, Dock icons, about-panel icons, and menu item icons. Other platforms keep the flag and ignore it.

#Menus and events

The tray menu is a native context menu. Action items call Click. Listen for click, double-click, enter, move, leave, menu-item, and scroll on OnEvent.

ShowMenu opens the menu at the cursor on macOS and Windows. Linux hosts own menu presentation and reject that call.

#Platform notes

Desktop.GetSupport reports TrayIcons and ProgrammableTrayPopup. Keep at most 32 tray icons.