{"id":49545368,"url":"https://github.com/gogpu/systray","last_synced_at":"2026-07-10T04:01:38.444Z","repository":{"id":354897984,"uuid":"1202171983","full_name":"gogpu/systray","owner":"gogpu","description":"Pure Go system tray library for Windows, macOS, and Linux. Zero CGO.","archived":false,"fork":false,"pushed_at":"2026-06-15T12:15:55.000Z","size":81,"stargazers_count":21,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T14:11:45.046Z","etag":null,"topics":["cross-platform","dbus","desktop","go","golang","linux","macos","notification-area","pure-go","statusbar","system-tray","tray-icon","wayland","windows","zero-cgo"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gogpu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-05T17:35:21.000Z","updated_at":"2026-06-15T12:16:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gogpu/systray","commit_stats":null,"previous_names":["gogpu/systray"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gogpu/systray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fsystray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fsystray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fsystray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fsystray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gogpu","download_url":"https://codeload.github.com/gogpu/systray/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fsystray/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35319810,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform","dbus","desktop","go","golang","linux","macos","notification-area","pure-go","statusbar","system-tray","tray-icon","wayland","windows","zero-cgo"],"created_at":"2026-05-02T19:00:21.866Z","updated_at":"2026-07-10T04:01:38.436Z","avatar_url":"https://github.com/gogpu.png","language":"Go","funding_links":[],"categories":["GUI"],"sub_categories":["Search and Analytic Databases"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/gogpu/.github/main/assets/logo.png\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/gogpu/.github/main/assets/logo.png\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/gogpu/.github/main/assets/logo.png\" alt=\"GoGPU Logo\" width=\"100\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003esystray\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePure Go system tray library for Windows, macOS, and Linux\u003c/strong\u003e\u003cbr\u003e\n  Zero CGO. Cross-platform. Multiple trays. Context menus. Notifications.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/gogpu/systray/actions\"\u003e\u003cimg src=\"https://github.com/gogpu/systray/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://app.codecov.io/gh/gogpu/systray\"\u003e\u003cimg src=\"https://codecov.io/gh/gogpu/systray/branch/main/graph/badge.svg\" alt=\"Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/gogpu/systray\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github.com/gogpu/systray.svg\" alt=\"Go Reference\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/gogpu/systray\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/gogpu/systray\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/gogpu/systray/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/gogpu/systray\"\u003e\u003cimg src=\"https://img.shields.io/badge/Pure_Go-Zero_CGO-brightgreen\" alt=\"Zero CGO\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Features\n\n- **Pure Go** — zero CGO on all platforms. Single binary, easy cross-compilation\n- **Multiple trays** — create as many tray icons as you need\n- **Context menus** — nested menus with checkboxes, separators, icons, and submenus\n- **Notifications** — balloon tips (Windows), notification center (macOS), D-Bus notifications (Linux)\n- **Dark mode** — automatic icon switching for light/dark themes (Windows)\n- **Template icons** — macOS-native monochrome icons that adapt to system theme\n- **Builder pattern** — fluent API for clean, readable code\n- **Message loop** — built-in `Run()` blocks and pumps the platform event loop\n- **Standalone** — no dependency on gogpu framework. Use in any Go application\n\n## Platform Implementation\n\n| Platform | API | Dependency | Status |\n|:---------|:----|:-----------|:------:|\n| **Windows** | `Shell_NotifyIconW` (shell32.dll) | `golang.org/x/sys/windows` | Implemented |\n| **macOS** | `NSStatusBar` / `NSStatusItem` (AppKit) | `github.com/go-webgpu/goffi` | Implemented |\n| **Linux** | StatusNotifierItem (D-Bus SNI) | `github.com/godbus/dbus/v5` | Implemented |\n\nAll platform implementations use Pure Go FFI — no C compiler required.\n\n## Installation\n\n```bash\ngo get github.com/gogpu/systray\n```\n\n**Requirements:** Go 1.25+\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"os\"\n\n    \"github.com/gogpu/systray\"\n)\n\nfunc main() {\n    tray := systray.New()\n\n    // Build context menu\n    menu := systray.NewMenu()\n    menu.Add(\"Hello\", func() { fmt.Println(\"Hello clicked!\") })\n    menu.Add(\"Show Notification\", func() {\n        tray.ShowNotification(\"My App\", \"Hello from systray!\")\n    })\n    menu.AddSeparator()\n    menu.AddCheckbox(\"Check me\", false, func() { fmt.Println(\"Toggled\") })\n    menu.AddSeparator()\n    menu.Add(\"Quit\", func() {\n        tray.Remove()\n        os.Exit(0)\n    })\n\n    // Configure and show\n    tray.SetIcon(iconPNG).\n        SetTooltip(\"My Application\").\n        SetMenu(menu)\n    tray.OnClick(func() { fmt.Println(\"Left click!\") })\n    tray.Show()\n\n    // Run the platform message loop (blocks until Quit)\n    if err := tray.Run(); err != nil {\n        fmt.Println(\"error:\", err)\n    }\n}\n```\n\n## API Reference\n\n### SystemTray\n\n```go\n// Create and lifecycle\ntray := systray.New()              // Create a new system tray icon\ntray.Show()                        // Show tray icon\ntray.Hide()                        // Hide tray icon (without removing)\ntray.Run()                         // Block and pump the platform message loop\ntray.Remove()                      // Destroy tray icon and release resources\n\n// Icon management\ntray.SetIcon(png []byte)           // Set tray icon (PNG format)\ntray.SetDarkModeIcon(png []byte)   // Auto-switch in dark mode (Windows)\ntray.SetTemplateIcon(png []byte)   // macOS template image (monochrome)\n\n// Text and menu\ntray.SetTooltip(text string)       // Hover tooltip\ntray.SetMenu(menu *Menu)           // Attach context menu\n\n// Events\ntray.OnClick(fn func())            // Left click handler\ntray.OnDoubleClick(fn func())      // Double click handler\ntray.OnRightClick(fn func())       // Right click handler\n\n// Notifications\ntray.ShowNotification(title, message string)  // OS-level notification\n\n// Position (for window placement near tray)\nx, y, w, h := tray.Bounds()       // Tray icon screen position\n```\n\nAll setter methods return `*SystemTray` for fluent chaining:\n```go\ntray.SetIcon(icon).SetTooltip(\"Ready\").SetMenu(menu).Show()\n```\n\n### Menu\n\n```go\nmenu := systray.NewMenu()\n\nmenu.Add(\"Label\", onClick)                          // Normal item\nmenu.AddCheckbox(\"Toggle\", checked, onChange)        // Checkbox item\nmenu.AddSeparator()                                 // Visual separator\nmenu.AddSubmenu(\"More\", submenu)                    // Nested submenu\nmenu.AddWithIcon(\"Save\", iconPNG, onClick)          // Item with icon\n```\n\nAll `Menu` methods return `*Menu` for chaining.\n\n### Multiple Trays\n\n```go\n// Each tray is independent with its own icon, menu, and handlers\nmainTray := systray.New().SetIcon(appIcon).SetMenu(mainMenu).Show()\nstatusTray := systray.New().SetIcon(statusIcon).SetTooltip(\"Status: OK\").Show()\n```\n\n## Dark Mode\n\nsystray supports automatic icon switching based on the system theme.\n\n**Windows** — Use `SetDarkModeIcon()` to provide an alternative icon for dark mode. The library detects theme changes via `WM_SETTINGCHANGE` with `\"ImmersiveColorSet\"` and switches icons automatically:\n\n```go\ntray.SetIcon(lightIcon).SetDarkModeIcon(darkIcon)\n```\n\n**macOS** — Use `SetTemplateIcon()` with a monochrome PNG. macOS renders template images with the correct color for the current menu bar appearance (light or dark). Only the alpha channel matters:\n\n```go\ntray.SetTemplateIcon(monochromeIcon)\n```\n\n**Linux** — The SNI protocol delivers the icon pixmap to the desktop environment, which handles theme adaptation. No special API is needed.\n\n## Notifications\n\n`ShowNotification` sends an OS-level notification from the tray icon:\n\n```go\ntray.ShowNotification(\"Update Available\", \"Version 2.0 is ready to install.\")\n```\n\n| Platform | Mechanism | Notes |\n|:---------|:----------|:------|\n| **Windows** | Balloon tip (`Shell_NotifyIconW` + `NIF_INFO`) | Appears near the tray icon |\n| **macOS** | `NSUserNotification` / Notification Center | Requires notification permission on macOS 13+ |\n| **Linux** | `org.freedesktop.Notifications` D-Bus | Works on GNOME, KDE, XFCE, and other FreeDesktop-compliant DEs |\n\n## Icon Guidelines\n\n| Platform | Recommended Size | Format | Notes |\n|:---------|:----------------|:-------|:------|\n| **Windows** | 16x16, 32x32 | PNG | Provide both sizes for standard and HiDPI |\n| **macOS** | 22x22, 44x44 (@2x) | PNG | Must be monochrome (template) for proper theme adaptation |\n| **Linux** | 22x22, 24x24 | PNG | SNI spec recommends 22x22 |\n\n**Input format:** PNG bytes (`[]byte`). The library handles conversion to native format (HICON, NSImage, ARGB pixmap) internally.\n\nFor macOS, use `SetTemplateIcon()` with a **monochrome** PNG (only alpha channel matters). The system automatically adjusts the icon color for light/dark menu bar.\n\n## Architecture\n\n```\nsystray.New()  -\u003e  SystemTray (public API)\n                       |\n                  PlatformTray (internal interface)\n                       |\n          +------------+------------+\n          |            |            |\n     Win32 impl   macOS impl   Linux impl\n     Shell_Notify  NSStatusBar   D-Bus SNI\n     IconW         NSStatusItem  StatusNotifierItem\n```\n\nFollows the Qt6 `QPlatformSystemTrayIcon` three-layer pattern. Each platform implementation is isolated in its own file with build constraints.\n\n## Usage with gogpu\n\nWhile systray is fully standalone, it integrates seamlessly with the [gogpu](https://github.com/gogpu/gogpu) application framework:\n\n```go\nimport (\n    \"github.com/gogpu/gogpu\"\n    \"github.com/gogpu/systray\"\n)\n\napp := gogpu.NewApp(config)\n\n// Create tray through the app (lifecycle managed automatically)\ntray := systray.New()\ntray.SetIcon(icon).SetMenu(menu).Show()\n\n// Minimize to tray pattern\napp.SetQuitBehavior(gogpu.QuitOnExplicitQuit)\napp.OnClose(func() bool {\n    app.Hide()       // hide window instead of closing\n    return false     // reject close\n})\ntray.OnClick(func() {\n    app.Show()       // restore window on tray click\n})\n```\n\n## Comparison with Alternatives\n\n| Feature | gogpu/systray | getlantern/systray | fyne-io/systray |\n|:--------|:------------:|:------------------:|:---------------:|\n| Pure Go (zero CGO) | **Yes** | No (CGO on macOS/Linux) | No (CGO on macOS/Linux) |\n| Multiple trays | **Yes** | No (single global) | No (single global) |\n| Dark mode icons | **Yes** | No | No |\n| Template icons (macOS) | **Yes** | No | Yes |\n| Nested menus | **Yes** | Yes | Yes |\n| Menu item icons | **Yes** | No | No |\n| Notifications | **Yes** | No | No |\n| Builder pattern | **Yes** | No | No |\n| Built-in message loop | **Yes** | Yes | Yes |\n| Wayland support | **Yes** (D-Bus SNI) | No | Partial |\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Part of the GoGPU Ecosystem\n\nsystray is part of the [GoGPU](https://github.com/gogpu) ecosystem — 790K+ lines of Pure Go, zero CGO. A GPU computing platform with a WebGPU implementation, shader compiler, 2D graphics library, and GUI toolkit.\n\n| Library | Purpose |\n|:--------|:--------|\n| [gogpu](https://github.com/gogpu/gogpu) | Application framework, windowing |\n| [wgpu](https://github.com/gogpu/wgpu) | Pure Go WebGPU (Vulkan/Metal/DX12/GLES) |\n| [naga](https://github.com/gogpu/naga) | Shader compiler (WGSL to SPIR-V/MSL/GLSL/HLSL/DXIL) |\n| [gg](https://github.com/gogpu/gg) | 2D graphics with GPU acceleration |\n| [ui](https://github.com/gogpu/ui) | GUI toolkit (22+ widgets, 4 themes) |\n| **[systray](https://github.com/gogpu/systray)** | **System tray (this library)** |\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgogpu%2Fsystray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgogpu%2Fsystray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgogpu%2Fsystray/lists"}