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.

Remarks

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.

Classes

TrayIcon

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

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

Warning

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 this object early, you need to call TrayIcon.close.

Example

import { TrayIcon } from '@tauri-apps/api/tray';
const tray = await TrayIcon.new({ tooltip: 'awesome tray tooltip' });
await tray.setTooltip('new tooltip');

Extends

Resource

Properties

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#L184

Accessors

rid

Get Signature

get rid(): number;

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

Returns

number

Inherited from

Resource.rid

Methods

[asyncDispose]()

asyncDispose: Promise<void>;

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

Returns

Promise<void>

Inherited from

Resource.[asyncDispose]

close()

close(): Promise<void>;

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

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.

Returns

Promise<void>

Remarks

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

Inherited from

Resource.close

setIcon()

setIcon(icon): Promise<void>;

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

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"] }

Parameters

Parameter	Type
`icon`	`JsImage` \| `null`

Returns

Promise<void>

Example

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

setIconAsTemplate()

setIconAsTemplate(asTemplate): Promise<void>;

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

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.

Parameters

Parameter	Type
`asTemplate`	`boolean`

Returns

Promise<void>

Example

await tray.setIconAsTemplate(true);

setIconWithAsTemplate()

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

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

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.

Parameters

Parameter	Type
`icon`	`JsImage` \| `null`
`asTemplate`	`boolean`

Returns

Promise<void>

Example

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

setMenu()

setMenu(menu): Promise<void>;

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

Sets a new tray menu.

Platform-specific:

Linux: once a menu is set it cannot be removed so null has no effect

Parameters

Parameter	Type
`menu`	\| `Submenu` \| `Menu` \| `null`

Returns

Promise<void>

Example

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

setMenuOnLeftClick()

setMenuOnLeftClick(onLeft): Promise<void>;

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

Disable or enable showing the tray menu on left click.

Platform-specific:

Linux: Unsupported.

Parameters

Parameter	Type
`onLeft`	`boolean`

Returns

Promise<void>

Deprecated

use TrayIcon.setShowMenuOnLeftClick instead.

Example

await tray.setShowMenuOnLeftClick(false);

setShowMenuOnLeftClick()

setShowMenuOnLeftClick(onLeft): Promise<void>;

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

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.

Parameters

Parameter	Type
`onLeft`	`boolean`

Returns

Promise<void>

Example

await tray.setShowMenuOnLeftClick(false);

Since

2.2.0

setTempDirPath()

setTempDirPath(path): Promise<void>;

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

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.

Parameters

Parameter	Type
`path`	`string` \| `null`

Returns

Promise<void>

Example

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

setTitle()

setTitle(title): Promise<void>;

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

Sets the title shown next to this tray icon.

Parameters

Parameter	Type
`title`	`string` \| `null`

Returns

Promise<void>

Example

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()

setTooltip(tooltip): Promise<void>;

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

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

Platform-specific:

Linux: Unsupported

Parameters

Parameter	Type
`tooltip`	`string` \| `null`

Returns

Promise<void>

Example

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

setVisible()

setVisible(visible): Promise<void>;

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

Show or hide this tray icon.

Parameters

Parameter	Type
`visible`	`boolean`

Returns

Promise<void>

Example

await tray.setVisible(false);

getById()

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

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

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.

Parameters

Parameter	Type
`id`	`string`

Returns

Promise<TrayIcon | null>

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

Example

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

new()

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

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

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.

Parameters

Parameter	Type
`options?`	`TrayIconOptions`

Returns

Promise<TrayIcon>

Example

import { TrayIcon } from '@tauri-apps/api/tray';
import { Menu } from '@tauri-apps/api/menu';
import { defaultWindowIcon } from '@tauri-apps/api/app';

const 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);
    }
  }
});

removeById()

static removeById(id): Promise<void>;

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

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.

Parameters

Parameter	Type
`id`	`string`

Returns

Promise<void>

Example

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

Interfaces

TrayIconOptions

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

`TrayIcon` creation options

Properties

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#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#L113
`iconAsTemplate?`	`boolean`	Use the icon as a template. macOS only.	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L139
`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#L100
`menu?`	\| `Submenu` \| `Menu`	The tray icon menu	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L102
~~`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#L149
`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#L159
`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#L135
`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#L128
`tooltip?`	`string`	The tray icon tooltip	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L115

Type Aliases

MouseButton

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

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

The mouse button that triggered a tray icon event.

MouseButtonState

type MouseButtonState = "Up" | "Down";

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

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

TrayIconClickEvent

type TrayIconClickEvent = object;

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

The extra fields of the Click and DoubleClick TrayIconEvent variants.

Properties

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#L66
`buttonState`	`MouseButtonState`	Mouse button state when this event was triggered.	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L68

TrayIconEvent

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#L79

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.

TrayIconEventBase

type TrayIconEventBase<T> = object;

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

The fields shared by every TrayIconEvent.

Type Parameters

Type Parameter
`T` extends `TrayIconEventType`

Properties

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#L53
`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#L55
`rect`	`object`	Position and size of the tray icon.	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L57
`rect.position`	`PhysicalPosition`	-	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L58
`rect.size`	`PhysicalSize`	-	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L59
`type`	`T`	The tray icon event type	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/tray.ts#L51

TrayIconEventType

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

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

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.

Support on Open Collective Sponsor on GitHub