Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 39 ยท Windows and Menus

System Tray Icons in Tauri

Add a system tray icon to a Tauri app: enable the tray-icon feature, build a TrayIconBuilder, attach a menu, react to clicks, update the icon and keep the app alive with no windows.

A tray icon (the notification area on Windows and Linux, the menu bar extras on macOS) lets an app stay available without taking space on screen: chat clients, sync tools, timers and clipboard managers all use one. Tauri 2 supports tray icons with a small amount of Rust.

Enable the feature

Tray support is optional. Turn it on in Cargo.toml:

TOML
tauri = { version = "2", features = ["tray-icon"] }

If you also want to use your app icon for the tray, add image-png or image-ico so Tauri can decode image files.

Create a tray icon

Create it in setup. Keep the menu and the icon tied to the app:

Rust
use tauri::{
    menu::{MenuBuilder, MenuItemBuilder},
    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent},
    Manager,
};

pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            let show = MenuItemBuilder::new("Show Window").id("show").build(app)?;
            let quit = MenuItemBuilder::new("Quit").id("quit").build(app)?;
            let menu = MenuBuilder::new(app).items(&[&show, &quit]).build()?;

            TrayIconBuilder::new()
                .icon(app.default_window_icon().unwrap().clone())
                .tooltip("Notes")
                .menu(&menu)
                .show_menu_on_left_click(false)
                .on_menu_event(|app, event| match event.id().as_ref() {
                    "show" => {
                        if let Some(w) = app.get_webview_window("main") {
                            let _ = w.show();
                            let _ = w.set_focus();
                        }
                    }
                    "quit" => app.exit(0),
                    _ => {}
                })
                .on_tray_icon_event(|tray, event| {
                    if let TrayIconEvent::Click {
                        button: MouseButton::Left,
                        button_state: MouseButtonState::Up,
                        ..
                    } = event
                    {
                        let app = tray.app_handle();
                        if let Some(w) = app.get_webview_window("main") {
                            let _ = w.show();
                            let _ = w.set_focus();
                        }
                    }
                })
                .build(app)?;
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error");
}

What each piece does:

  • .icon(...) the image. Use a simple, high-contrast, small image; on macOS you may supply a template image with .icon_as_template(true) so it adapts to light and dark menu bars.
  • .tooltip(...) text on hover (not supported everywhere, for example on Linux it depends on the desktop environment).
  • .menu(&menu) attaches a menu built with the same menu API.
  • .show_menu_on_left_click(false) makes only right-click open the menu on Windows and Linux, leaving left-click free for a custom action. (On macOS both clicks usually open it.)
  • .on_menu_event(...) handles menu clicks, by id.
  • .on_tray_icon_event(...) receives clicks, double-clicks, enter, move and leave events, with the click position and the icon rectangle.

Keep running when the window closes

A tray app typically hides instead of quitting. Intercept the close request of the main window and hide it:

Rust
.on_window_event(|window, event| {
    if let tauri::WindowEvent::CloseRequested { api, .. } = event {
        let _ = window.hide();
        api.prevent_close();
    }
})

Now "Quit" in the tray menu is the only way out, which is exactly how tray apps should work. Give the user that Quit item; apps that cannot be quit are frustrating.

Updating the tray later

Keep the returned TrayIcon or fetch it with app.tray_by_id("main"). Then change it live:

Rust
let tray = app.tray_by_id("main").unwrap();
tray.set_tooltip(Some("3 unread notes"))?;
tray.set_icon(Some(unread_icon))?;
tray.set_visible(true)?;

Give the tray an id with TrayIconBuilder::with_id("main") so you can find it again.

Tray from JavaScript

The JavaScript API can create a tray as well (TrayIcon.new({ ... }) from @tauri-apps/api/tray), with core:tray:default permissions. Rust is the more common choice because the tray usually lives for the whole app lifetime.

Platform notes

  • Windows: icons may hide in the overflow area; users can pin them. Use .ico or PNG.
  • macOS: the item appears in the menu bar. Use a template image (monochrome with transparency) for crisp light and dark mode.
  • Linux: tray support depends on the desktop environment. Some (like GNOME) need an extension to show tray icons. Do not make the tray the only way to reach your app on Linux.
  • Mobile platforms have no tray.

Try it: a tray controller (stand-in)

This stand-in models the state machine: a hidden-vs-visible window, a tray menu, a close request that hides and a quit that really exits.

Node.js Stand-in: hide on close, quit from the tray

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Try it: tray click handling (stand-in)

Node.js Stand-in: left-click, right-click, double-click

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You have now covered commands, events, windows and menus. The next part of the tutorial covers plugins and native features such as the file system and dialogs; for the full course outline see the Tauri track page.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do you need in Cargo.toml for tray icons?

    The tray is an optional feature of tauri.
  2. 2. How does a tray app keep running when its window is closed?

    Intercept CloseRequested, hide instead and offer a Quit item.
  3. 3. Why give the tray an id?

    An id lets you retrieve the tray later to change its tooltip, icon or visibility.
  4. 4. Which platform may need an extension to show tray icons?

    Tray support on Linux depends on the desktop environment.

Summary

  • Enable the tray-icon feature and build the tray with TrayIconBuilder in setup.
  • Attach a menu and handle menu events and tray click events.
  • For tray apps, hide the main window on close and provide a Quit item.
  • Give the tray an id to update its icon and tooltip later.
  • Tray behavior varies by platform; do not depend on it as the only entry point.

Next: The Tauri Plugin System