tray_manager is built on nativeapi, a Flutter binding of one C++ core library (libnativeapi/nativeapi) shared by macOS, Windows and Linux. Coming from 0.5.x? See Upgrading from 0.5.x.

This package lets Flutter desktop apps put an icon, with a tooltip, a title and a context menu, in the system tray.

English | 简体中文

• Platform Support
• Screenshots
• Known Issues
  • Not Showing in GNOME
• Quick Start
  • Installation
    • Requirements
  • Usage
    • Upgrading from 0.5.x
    • Moving to the native API
• Who's using it?
• API
  • Native API
• License

macOS	Linux	Windows

On Linux the tray icon is a StatusNotifierItem, which needs a panel that hosts them. KDE Plasma and most other desktops do; GNOME does only with the AppIndicator extension (Ubuntu ships it enabled).

Add this to your package's pubspec.yaml file:

dependencies:
  tray_manager: ^0.7.0

Or

dependencies:
  tray_manager:
    git:
      url: https://github.com/leanflutter/tray_manager.git
      ref: main

• Flutter 3.47 / Dart 3.13 or later, macOS 10.15 or later.
• Linux build machines need GTK 3, X11 and Xi development files. The tray icon is a StatusNotifierItem over D-Bus, so libayatana-appindicator3-dev is no longer needed.

sudo apt-get install libgtk-3-dev libx11-dev libxi-dev

import 'package:tray_manager/tray_manager.dart';

final trayIcon = TrayIcon.create()!;
trayIcon.icon = ImageAsset.fromAsset('images/tray_icon.png');
trayIcon.setTooltip('tray_manager');

final menu = Menu.create()!;
final showWindowItem = MenuItem.createWithLabelAndType(
  'Show Window',
  MenuItemType.normal,
)!;
showWindowItem.addListener((event) {
  if (event is MenuItemClickedEvent) {
    // Show the application window.
  }
});
menu.addItem(showWindowItem);
menu.addSeparator();
menu.addItem(MenuItem.createWithLabelAndType('Exit App', MenuItemType.normal));

trayIcon.setContextMenu(menu);
trayIcon.setVisible(true);

The example app of this plugin covers the 0.5.x compatible API. For the full example — several icons, animated icons, every native property — see nativeapi's tray_icon_example.

Code written for tray_manager 0.5.x keeps working by importing package:tray_manager/legacy.dart instead of package:tray_manager/tray_manager.dart. It provides the old trayManager, TrayListener, Menu and MenuItem (menu_base is no longer a dependency) on top of the native API.

The import has to change on purpose: legacy.dart is a bridge, not the future of this package. Its classes are marked @Deprecated and will be removed in a later release — move to the native API above when you can.

import 'package:tray_manager/legacy.dart';

await trayManager.setIcon('images/tray_icon.png');
await trayManager.setToolTip('tray_manager');
await trayManager.setContextMenu(
  Menu(
    items: [
      MenuItem(key: 'show_window', label: 'Show Window'),
      MenuItem.separator(),
      MenuItem(key: 'exit_app', label: 'Exit App'),
    ],
  ),
);

What differs from 0.5.x:

• Builds need Flutter 3.47 / Dart 3.13 and macOS 10.15 (0.5.x: Flutter 3.3, macOS 10.11).
• A click is reported when it completes, as onTrayIconMouseDown immediately followed by onTrayIconMouseUp (same for the right button). 0.5.x sent the two separately on macOS and only the first on Windows. Linux still reports no tray icon clicks at all: the panel keeps them and opens the menu itself.
• Calls a platform has no use for are ignored instead of throwing MissingPluginException: setTitle and setIconPosition on Windows; setIconPosition, popUpContextMenu and getBounds (which answers null) on Linux. setToolTip now works on Linux.
• setIcon throws an ArgumentError when the image cannot be loaded, on every platform. Windows takes .png as well as .ico now.
• bringAppToFront of popUpContextMenu is accepted but ignored.
• MenuItem.onClick runs once per click, also when no TrayListener is registered.
• label, toolTip, checked and disabled of a MenuItem update the visible menu as soon as they are assigned; adding or removing items still needs another setContextMenu call.
• sublabel, onHighlight and onLoseHighlight are kept but unused.

Keep a reference to every TrayIcon for as long as it should be shown: a wrapper that is garbage-collected releases its native handle, and that removes the icon. A Menu or MenuItem that is attached stays alive natively, but keep the ones you want to change later.

• Airclap - Send any file to any device. cross platform, ultra fast and easy to use.
• Biyi (比译) - A convenient translation and dictionary app.
• scrcpy buddy 🤝 - A GUI for scrcpy built with Fluent Design.

tray_manager now re-exports tray-related APIs from nativeapi, including TrayIcon, TrayManager, Menu, MenuItem, Image, and tray/menu events. Import package:tray_manager/legacy.dart only for code that still uses the 0.5.x API.

MIT