Skip to content

tray

Create and manipulate system tray (menu bar / notification area) icons.

Tray icons are created with TrayIcon.new and live on the Rust side, the frontend only holds a handle to them.

This package is also accessible with window.__TAURI__.tray when app.withGlobalTauri in tauri.conf.json is set to true.

All commands used by this module are part of the core:tray:default permission set, which is enabled by default, so no extra capability configuration is needed. Loading an icon from a path or from bytes additionally requires the image-png / image-ico Cargo features of the tauri crate.

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L230

Tray icon class and associated methods. This type constructor is private, instead, you should use the static method TrayIcon.new.

Unlike Rust, JavaScript does not have any way to run cleanup code when an object is being removed by garbage collection, but this tray icon will be cleaned up when the tauri app exists, however if you want to cleanup and remove the tray early, you need to call TrayIcon.close.

import { TrayIcon } from '@tauri-apps/api/tray';
const tray = await TrayIcon.new({ tooltip: 'awesome tray tooltip' });
await tray.setTooltip('new tooltip');
Property Modifier Type Description Defined in
id public string The id associated with this tray icon. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L232

get rid(): number;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L560

number

Resource.rid

asyncDispose: Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L581

Promise<void>

Resource.[asyncDispose]

close(): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L575

Destroys and cleans up this resource from memory. You should not call any method on this object anymore and should drop any reference to it.

Promise<void>

Uses the core:resources:allow-close permission, which is part of the core:resources:default permission set enabled by default.

Resource.close

setIcon(icon): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L347

Sets a new tray icon. If null is provided, it will remove the icon.

Note that you may need the image-ico or image-png Cargo features to use this API. To enable it, change your Cargo.toml file:

[dependencies]
tauri = { version = "...", features = ["...", "image-png"] }
Parameter Type
icon JsImage | null

Promise<void>

import { Image } from '@tauri-apps/api/image';
await tray.setIcon(await Image.fromPath('icons/active.png'));
// remove the icon
await tray.setIcon(null);

setIconAsTemplate(asTemplate): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L523

Sets the current icon as a template. macOS only

A template image is recolored by the system so it matches the menu bar appearance in light and dark mode.

Parameter Type
asTemplate boolean

Promise<void>

use TrayIcon.setIconTemplated instead, which sets the icon and draws it as a template in one call.

await tray.setIconAsTemplate(true);

setIconTemplated(icon): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L497

Sets a new tray icon, or removes it, and draws it as a template.

A template image is drawn using only its alpha channel, so the system recolors it to match the menu bar in light and dark mode. TrayIcon.setIcon draws the icon as-is instead.

Note that you may need the image-ico or image-png Cargo features to use this API. To enable it, change your Cargo.toml file:

[dependencies]
tauri = { version = "...", features = ["...", "image-png"] }

Platform-specific:

Parameter Type
icon JsImage | null

Promise<void>

import { Image } from '@tauri-apps/api/image';
await tray.setIconTemplated(await Image.fromPath('icons/active.png'));
// remove the icon
await tray.setIconTemplated(null);

2.13.0

setIconWithAsTemplate(icon, asTemplate): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L554

Sets a new tray icon and template status atomically. macOS only.

Note that you may need the image-ico or image-png Cargo features to use this API. To enable it, change your Cargo.toml file:

[dependencies]
tauri = { version = "...", features = ["...", "image-png"] }

Prefer this over calling TrayIcon.setIcon and TrayIcon.setIconAsTemplate in sequence, which can briefly show the new icon with the previous template setting.

Parameter Type
icon JsImage | null
asTemplate boolean

Promise<void>

use TrayIcon.setIconTemplated for a template icon, or TrayIcon.setIcon for a plain one.

import { Image } from '@tauri-apps/api/image';
await tray.setIconWithAsTemplate(await Image.fromPath('icons/active.png'), true);

setMenu(menu): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L397

Sets a new tray menu.

Platform-specific:

  • Linux: once a menu is set it cannot be removed so null has no effect
Parameter Type
menu | Submenu | Menu | null

Promise<void>

import { Menu } from '@tauri-apps/api/menu';
await using menu = await Menu.new({ items: [{ id: 'quit', text: 'Quit' }] });
await tray.setMenu(menu);

setMenuOnLeftClick(onLeft): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L583

Disable or enable showing the tray menu on left click.

Platform-specific:

  • Linux: Unsupported.
Parameter Type
onLeft boolean

Promise<void>

use TrayIcon.setShowMenuOnLeftClick instead.

await tray.setShowMenuOnLeftClick(false);

setNativeIcon(icon): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L379

Sets a new tray icon from a platform-native icon, or removes it if null is provided.

Note that this overrides any icon set with TrayIcon.setIcon.

Platform-specific:

  • Linux: Known variants map to freedesktop icon names, so the icon is resolved by the desktop icon theme and follows its light and dark variants.
  • macOS: Known variants map to AppKit image names.
  • Windows: Known variants map to stock shell icons where an equivalent exists, and an error is thrown otherwise.
Parameter Type
icon | NativeIcon | null

Promise<void>

import { NativeIcon } from '@tauri-apps/api/menu';
await tray.setNativeIcon(NativeIcon.StatusAvailable);
// remove the icon
await tray.setNativeIcon(null);

2.13.0

setShowMenuOnLeftClick(onLeft): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L608

Disable or enable showing the tray menu on left click.

Platform-specific:

  • Linux: Unsupported.

Disable it to handle left clicks yourself through the TrayIconOptions.action handler while still showing the menu on right click.

Parameter Type
onLeft boolean

Promise<void>

await tray.setShowMenuOnLeftClick(false);

2.2.0

setShowMenuOnRightClick(onRight): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L629

Disable or enable showing the tray menu on right click.

Platform-specific:

  • Linux: Unsupported.
Parameter Type
onRight boolean

Promise<void>

await tray.setShowMenuOnRightClick(false);

2.13.0

setTempDirPath(path): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L466

Sets the tray icon temp dir path. Linux only.

On Linux, we need to write the icon to the disk and usually it will be $XDG_RUNTIME_DIR/tray-icon or $TEMP/tray-icon.

Parameter Type
path string | null

Promise<void>

import { appCacheDir } from '@tauri-apps/api/path';
await tray.setTempDirPath(await appCacheDir());

setTitle(title): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L438

Sets the title shown next to this tray icon.

Parameter Type
title string | null

Promise<void>

await tray.setTitle('42');

Platform-specific:

  • Linux: The title will not be shown unless there is an icon as well. The title is useful for numerical and other frequently updated information. In general, it shouldn’t be shown unless a user requests it as it can take up a significant amount of space on the user’s panel. This may not be shown in all visualizations.
  • Windows: Unsupported

setTooltip(tooltip): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L417

Sets the tooltip for this tray icon, shown when the cursor hovers it.

Platform-specific:

  • Linux: Unsupported
Parameter Type
tooltip string | null

Promise<void>

await tray.setTooltip('3 unread messages');

setVisible(visible): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L450

Show or hide this tray icon.

Parameter Type
visible boolean

Promise<void>

await tray.setVisible(false);

showMenu(): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L654

Show the tray menu at the current cursor position.

Useful with TrayIconOptions.showMenuOnLeftClick and TrayIconOptions.showMenuOnRightClick disabled, to control when the menu shows up, for instance after updating its items.

Platform-specific:

  • Linux: Unsupported.

Promise<void>

await tray.showMenu();

2.13.0

static getById(id): Promise<TrayIcon | null>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L254

Gets a tray icon using the provided id.

Use it to get a handle from the frontend to a tray icon that was created on the Rust side with an explicit id.

Parameter Type
id string

Promise<TrayIcon | null>

The tray icon, or null if no tray icon with that id exists.

import { TrayIcon } from '@tauri-apps/api/tray';
const tray = await TrayIcon.getById('main-tray');
await tray?.setTooltip('still here');

static new(options?): Promise<TrayIcon>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L307

Creates a new TrayIcon

Platform-specific:

  • Linux: Sometimes the icon won’t be visible unless a menu is set. Setting an empty Menu is enough.
Parameter Type
options? TrayIconOptions

Promise<TrayIcon>

import { TrayIcon } from '@tauri-apps/api/tray';
import { Menu } from '@tauri-apps/api/menu';
import { defaultWindowIcon } from '@tauri-apps/api/app';
await using menu = await Menu.new({
items: [{ id: 'quit', text: 'Quit', action: () => console.log('quit') }]
});
const tray = await TrayIcon.new({
id: 'main-tray',
icon: (await defaultWindowIcon()) ?? undefined,
menu,
tooltip: 'My app',
action: (event) => {
if (event.type === 'Click') {
console.log('tray clicked with', event.button);
}
}
});

static removeById(id): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L272

Removes a tray icon using the provided id from tauri’s internal state.

Note that this may cause the tray icon to disappear if it wasn’t cloned somewhere else or referenced by JS.

Parameter Type
id string

Promise<void>

import { TrayIcon } from '@tauri-apps/api/tray';
await TrayIcon.removeById('main-tray');

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L99

`TrayIcon` creation options

Property Type Description Defined in
action? (event) => void A handler for an event on the tray icon. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L209
autosaveName? string A stable key for this tray icon’s saved position in the menu bar. macOS only. macOS restores where the user Cmd+dragged a tray icon on the next launch either way, keyed by the order in which the app created its tray icons (Item-0, Item-1, and so on) when no name is given. Set one when that numbering isn’t stable from launch to launch, as in an app that creates several tray icons or creates one conditionally, so that two icons don’t come back holding each other’s positions. Use one fixed string per tray icon, typically a reverse-DNS identifier such as "com.example.app.tray". The position is saved under that name, so changing it abandons the position saved under the old one. Since 2.13.0 Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L161
icon? JsImage The tray icon which could be icon bytes or path to the icon file. Note that you may need the image-ico or image-png Cargo features to use this API. To enable it, change your Cargo.toml file: [dependencies] tauri = { version = "...", features = ["...", "image-png"] } Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L114
iconAsTemplate? boolean Use the icon as a template. macOS only. Deprecated use TrayIconOptions.iconIsTemplate instead. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L168
iconIsTemplate? boolean Draw the icon as a template. macOS only. A template image is drawn using only its alpha channel, so the system recolors it to match the menu bar in light and dark mode. Since 2.13.0 Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L177
id? string The tray icon id. If undefined, a random one will be assigned Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L101
menu? | Submenu | Menu The tray icon menu Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L103
menuOnLeftClick? boolean Whether to show the tray menu on left click or not, default is true. Platform-specific: - Linux: Unsupported. Deprecated use TrayIconOptions.showMenuOnLeftClick instead. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L187
nativeIcon? NativeIcon The tray icon from a platform-native icon, ignored when TrayIconOptions.icon is set. See TrayIcon.setNativeIcon for the platform-specific behavior. Since 2.13.0 Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L123
showMenuOnLeftClick? boolean Whether to show the tray menu on left click or not, default is true. Platform-specific: - Linux: Unsupported. Since 2.2.0 Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L197
showMenuOnRightClick? boolean Whether to show the tray menu on right click or not, default is true. Platform-specific: - Linux: Unsupported. Since 2.13.0 Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L207
tempDirPath? string The tray icon temp dir path. Linux only. On Linux, we need to write the icon to the disk and usually it will be $XDG_RUNTIME_DIR/tray-icon or $TEMP/tray-icon. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L145
title? string The tray title Platform-specific - Linux: The title will not be shown unless there is an icon as well. The title is useful for numerical and other frequently updated information. In general, it shouldn’t be shown unless a user requests it as it can take up a significant amount of space on the user’s panel. This may not be shown in all visualizations. - Windows: Unsupported. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L138
tooltip? string The tray icon tooltip Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L125

type MouseButton = "Left" | "Right" | "Middle";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L31

The mouse button that triggered a tray icon event.


type MouseButtonState = "Up" | "Down";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L28

Whether the mouse button was pressed (Down) or released (Up).


type TrayIconClickEvent = object;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L65

The extra fields of the Click and DoubleClick TrayIconEvent variants.

Property Type Description Defined in
button MouseButton Mouse button that triggered this event. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L67
buttonState MouseButtonState Mouse button state when this event was triggered. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L69

type TrayIconEvent =
| TrayIconEventBase<"Click"> & TrayIconClickEvent
| TrayIconEventBase<"DoubleClick"> & Omit<TrayIconClickEvent, "buttonState">
| TrayIconEventBase<"Enter">
| TrayIconEventBase<"Move">
| TrayIconEventBase<"Leave">;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L80

Describes a tray icon event.

Platform-specific:

  • Linux: Unsupported. The event is not emitted even though the icon is shown, the icon will still show a context menu on right click.

type TrayIconEventBase<T> = object;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L50

The fields shared by every TrayIconEvent.

Type Parameter
T extends TrayIconEventType
Property Type Description Defined in
id string Id of the tray icon which triggered this event. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L54
position PhysicalPosition Physical position of the click the triggered this event. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L56
rect object Position and size of the tray icon. Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L58
rect.position PhysicalPosition - Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L59
rect.size PhysicalSize - Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L60
type T The tray icon event type Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L52

type TrayIconEventType = "Click" | "DoubleClick" | "Enter" | "Move" | "Leave";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L42

The kind of a TrayIconEvent.

  • Click: a mouse button was pressed or released over the icon.
  • DoubleClick: the icon was double clicked.
  • Enter: the cursor entered the icon area.
  • Move: the cursor moved inside the icon area.
  • Leave: the cursor left the icon area.

© 2026 Tauri Contributors. CC-BY / MIT