systray

On macOS, you must wrap your binary in an application bundle. Create a folder structure like this:

SystrayApp.app/
  Contents/
    Info.plist
    MacOS/
      go-executable
    Resources/
      SystrayApp.icns

To avoid a blurry icon/text, add this to Info.plist:

<key>NSHighResolutionCapable</key>
<string>True</string>

To prevent the app from showing in the Dock, add this to Info.plist:

<key>LSUIElement</key>
<string>1</string>

To prevent a command prompt/console window from appearing when your application starts on Windows, use the -H=windowsgui linker flag during build:

env GO111MODULE=on go build -ldflags "-H=windowsgui"

Building systray on Linux requires gcc and the gtk3 and libayatana-appindicator3 development headers.

For Debian or Ubuntu, install them with:

sudo apt-get install gcc libgtk-3-dev libayatana-appindicator3-dev

On Linux Mint, libxapp-dev is also required.

If you need to support the older libappindicator3 library, build with the legacy_appindicator tag:

go build -tags=legacy_appindicator

Use systray.AddMenuItem(title, tooltip) to create a new menu item.

Menu items support being checked or disabled. On macOS and Windows, you can also set a specific icon for a menu item using mQuit.SetIcon(iconData).

func onReady() {
	mQuit := systray.AddMenuItem("Quit", "Quit the whole app")

	// Sets the icon of a menu item. Only available on Mac and Windows.
	mQuit.SetIcon(iconData)
}

On macOS, you can allow users to cmd-drag the icon off the menu bar by calling:

systray.SetRemovalAllowed(true)

Inside the onReady callback, you can configure the visual properties of the system tray icon using the following methods:

• systray.SetIcon(data): Sets the icon image.
• systray.SetTitle(title): Sets the title text.
• systray.SetTooltip(tooltip): Sets the tooltip text.

To start the system tray application, call systray.Run(onReady, onExit).

• onReady: A callback function executed when the tray is ready. Use this to set the icon, title, tooltip, and add menu items.
• onExit: A callback function executed when the application is exiting. Use this for cleanup tasks.

func main() {
	systray.Run(onReady, onExit)
}

func onReady() {
	// Setup tray here
}

func onExit() {
	// Cleanup here
}

You can build a menu hierarchy using the following methods. These can be safely called from different goroutines.

• systray.AddMenuItem(title, tooltip): Adds a standard menu item.
• systray.AddMenuItemCheckbox(title, tooltip, checked): Adds a menu item with a checkbox. Note: On Windows and OSX, items are checkable by default, but on Linux, you must use this method or the AddSubMenuItemCheckbox variant.
• systray.AddSeparator(): Adds a visual separator bar to the menu.
• item.AddSubMenuItem(title, tooltip): Adds a nested menu item under an existing MenuItem.
• item.AddSubMenuItemCheckbox(title, tooltip, checked): Adds a nested checkbox item under an existing MenuItem (required for Linux checkbox support).

To start the system tray, use either systray.Run() or systray.Register().

• systray.Run(onReady, onExit): Initializes the GUI and starts the event loop. This is a blocking call and must be run from the main thread on macOS. It executes onReady when the tray is ready and onExit when the tray is quitting.
• systray.Register(onReady, onExit): Initializes the GUI and registers callbacks but does not block. This is useful if your application needs to run other UI elements (like a webview) alongside the tray. You must manage the event loop elsewhere.

onReady is called when the tray is initialized. onExit is called when the tray is being shut down.

You can dynamically update the state of a MenuItem using the following methods:

• item.SetTitle(title): Changes the displayed text.
• item.SetTooltip(tooltip): Changes the hover tooltip.
• item.Enable() / item.Disable(): Toggles whether the item is interactive (grayed out if disabled).
• item.Check() / item.Uncheck(): Toggles the check mark.
• item.Show() / item.Hide(): Controls the visibility of the item.
• item.Checked(): Returns true if the item is currently checked.
• item.Disabled(): Returns true if the item is currently disabled.