# Tray

A tray is a small icon placed in the OS status area (macOS menu bar, Windows system tray, or Linux app indicator area). Users can click or right-click the icon, and in most cases you'll attach a [menu](/deskifier/menus.md) to it via [Set Tray Menu](#set-tray-menu).

### Tray Icon Sizing

Each platform expects a different icon size. For best results, supply a platform-specific image. For a quick-and-easy setup, pass a single 64×64 @ 144 DPI PNG and Deskifier will rescale it.

<table><thead><tr><th width="130.33333333333331">Platform</th><th width="239">Desired Size &#x26; Type</th><th>Notes</th></tr></thead><tbody><tr><td>macOS</td><td>32x32 (144 DPI) .png</td><td>Set <code>darkModeSupport: true</code> to treat the icon as a <a href="https://www.electronjs.org/docs/latest/api/native-image#template-image-macos"><mark style="color:blue;">TemplateImage</mark></a>, which adapts to light/dark menu bars.</td></tr><tr><td>Windows</td><td>64x64 .png</td><td></td></tr><tr><td>Linux</td><td>24x24 .png</td><td></td></tr></tbody></table>

## Methods

### <mark style="color:purple;">Create Tray</mark>

Creates a tray instance.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.create({ arguments })
```

**Arguments**

* `iconOptions` <mark style="color:green;">Object</mark>\
  Optional. By default, the app icon will be used.
  * `url` <mark style="color:green;">String</mark> (Conditionally Required)\
    The web URL of the resource. Not required if an exact path is given.
  * `path` <mark style="color:green;">String</mark> (Conditionally Required)\
    The local filesystem path of the icon. Not required if a url is given.
  * `darkModeSupport` <mark style="color:green;">Boolean</mark>\
    Treats the icon as a template image so it adapts to light/dark menu bars. **macOS only.**

**Returns**

* `trayId` <mark style="color:green;">String</mark>\
  The ID of the new tray.
* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.

**Example**

```javascript
const tray = await window.deskifier.tray.create({
    iconOptions: {
        url: 'https://www.deskifier.com/windowsTrayIcon.png'
    }
});

console.log(tray.trayId);
// '7795d507-bf71-41d2-a505-16a0e48fe651'
```

{% endtab %}
{% endtabs %}

***

### <mark style="color:purple;">Destroy Tray</mark>

Destroys a tray instance.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.destroy({ arguments })
```

**Arguments**

* `id` <mark style="color:green;">String</mark> (Required)

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Set Tray Icon</mark>

Sets the tray icon. Refer to the create tray action for more details.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.setIcon({ arguments })
```

**Arguments**

* `iconOptions` <mark style="color:green;">Object</mark> (Required)
  * `url` <mark style="color:green;">String</mark> (Required)\
    The URL of the resource.
  * `darkModeSupport` <mark style="color:green;">Boolean</mark>\
    Attempts to make the icon compatible with dark mode (macOS only)
* `id` <mark style="color:green;">String</mark> (Required)

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Set Tray Tool Tip</mark>

Sets the tray tool tip.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.setToolTip({ arguments })
```

**Arguments**

* `toolTip` <mark style="color:green;">String</mark> (Required)
* `id` <mark style="color:green;">String</mark> (Required)

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Set Tray Menu</mark>

Attaches a menu to a tray icon. The menu must already be created via [Create Tray Menu](/deskifier/menus.md#create-tray-menu).

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.setMenu({ arguments })
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark> (Required)
* `menuId` <mark style="color:green;">String</mark> (Required)

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Set Tray Title</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Sets the title displayed next to the tray icon in the status bar.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.setTitle({ arguments })
```

**Arguments**

* `title` <mark style="color:green;">String</mark> (Required)
* `id` <mark style="color:green;">String</mark> (Required)

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Display Tray Balloon</mark>

<mark style="color:purple;background-color:purple;">**Windows**</mark> Displays a balloon-style notification anchored to the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.displayBalloon({ arguments })
```

**Arguments**

* `id` <mark style="color:green;">String</mark> (Required)
* `balloonOptions` <mark style="color:green;">Object</mark> (Required)
  * `title` <mark style="color:green;">String</mark> (Required)
  * `content` <mark style="color:green;">String</mark> (Required)
  * `iconType` <mark style="color:green;">String</mark>\
    One of `'none'`, `'info'`, `'warning'`, `'error'`, or `'custom'`. Default is `'none'`.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Remove Tray Balloon</mark>

<mark style="color:purple;background-color:purple;">**Windows**</mark> Removes the tray balloon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.removeBalloon({ arguments })
```

**Arguments**

* `id` <mark style="color:green;">String</mark> (Required)

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

## Properties

### <mark style="color:purple;">Get Tray Title</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Returns the title displayed next to the tray icon in the status bar.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.getTitle({ arguments })
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark> (Required)

**Returns**

* `title` <mark style="color:green;">String</mark>
* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Get All Trays</mark>

Returns all active trays, including each tray's attached menus and destroy state.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.getAll()
```

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
* `trays` <mark style="color:green;">Array Of Objects</mark>
  * `id` <mark style="color:green;">String</mark>\
    The ID of the tray.
  * `menuIds` <mark style="color:green;">Array of Strings</mark>\
    IDs of any menus currently attached to this tray. Empty array if no menu is attached.
  * `isDestroyed` <mark style="color:green;">Boolean</mark>\
    `true` if the tray has been destroyed.
    {% endtab %}
    {% endtabs %}

***

### <mark style="color:purple;">Is Destroyed</mark>

Checks whether a specific tray has been destroyed. Useful for handling stale references.

{% hint style="info" %}
After [Destroy Tray](#destroy-tray), the tray is fully removed from the internal registry. Calling this method with that tray's ID returns `{ success: false }`. For still-alive trays it returns `{ success: true, destroyed: false }`.
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.tray.isDestroyed({ arguments })
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark> (Required)

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  `true` if the tray exists. `false` if the tray was fully destroyed or the ID is unknown.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
* `destroyed` <mark style="color:green;">Boolean</mark>\
  `true` if the tray is currently marked destroyed, `false` if alive.
  {% endtab %}
  {% endtabs %}

***

## Events

### <mark style="color:purple;">Click</mark>

Fires when the tray icon is clicked.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onClick((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `bounds` [<mark style="color:blue;">Electron.Rectangle</mark>](https://www.electronjs.org/docs/latest/api/structures/rectangle)
* `position` [<mark style="color:blue;">Electron.Point</mark>](https://www.electronjs.org/docs/latest/api/structures/point)

**Example**

```javascript
window.deskifier.tray.onClick((data) => {
   console.log(data.trayId, data.event, data.bounds, data.position);
});

/*
{
    "trayId": "33f13130-62ad-471c-b46a-75fd75e2f099",
    "event": {
        "shiftKey": false,
        "ctrlKey": false,
        "altKey": false,
        "metaKey": false,
        "triggeredByAccelerator": true
    },
    "bounds": {
        "x": 1675,
        "y": 1040,
        "width": 24,
        "height": 40
    },
    "position": {
        "x": 1684,
        "y": 1061
    }
}
*/
```

{% endtab %}
{% endtabs %}

***

### <mark style="color:purple;">Right Click</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> <mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the tray icon is right clicked.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onRightClick((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `bounds` [<mark style="color:blue;">Electron.Rectangle</mark>](https://www.electronjs.org/docs/latest/api/structures/rectangle)
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Double Click</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> <mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the tray icon is double clicked.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onDoubleClick((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `bounds` [<mark style="color:blue;">Electron.Rectangle</mark>](https://www.electronjs.org/docs/latest/api/structures/rectangle)
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Middle Click</mark>

<mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the tray icon is middle clicked.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onMiddleClick((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `bounds` [<mark style="color:blue;">Electron.Rectangle</mark>](https://www.electronjs.org/docs/latest/api/structures/rectangle)
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Balloon Show</mark>

<mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the tray balloon shows.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onBalloonShow((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Balloon Click</mark>

<mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the tray balloon is clicked.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onBalloonClick((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Balloon Closed</mark>

<mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the tray balloon is closed because of timeout or user manually closes it.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onBalloonClosed((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Drop</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Fires when any dragged items are dropped on the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onDrop((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Drop Files</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Fires when dragged files are dropped in the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onDropFiles((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `files` <mark style="color:green;">Array</mark>
  * `file` <mark style="color:green;">String</mark>\
    The paths of the dropped files.
    {% endtab %}
    {% endtabs %}

***

### <mark style="color:purple;">Drop Text</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Fires when dragged text is dropped in the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onDropText((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `text` <mark style="color:green;">String</mark>\
  The dropped text string.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Drag Enter</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Fires when a drag operation enters the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onDragEnter((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Drag Leave</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Fires when a drag operation exits the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onDragLeave((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Drag End</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Fires when a drag operation ends on the tray or ends at another location.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onDragEnd((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Mouse Up</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Fires when the mouse is released from clicking the tray icon.

{% hint style="info" %}
This will not be emitted if you have set a context menu for your Tray as a result of macOS-level constraints.
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onMouseUp((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `position` [<mark style="color:blue;">Electron.Point</mark>](https://www.electronjs.org/docs/latest/api/structures/point)
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Mouse Down</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Fires when the mouse clicks the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onMouseDown((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `position` [<mark style="color:blue;">Electron.Point</mark>](https://www.electronjs.org/docs/latest/api/structures/point)
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Mouse Enter</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> <mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the mouse enters the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onMouseEnter((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `position` [<mark style="color:blue;">Electron.Point</mark>](https://www.electronjs.org/docs/latest/api/structures/point)
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Mouse Leave</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> <mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the mouse exits the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onMouseLeave((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `position` [<mark style="color:blue;">Electron.Point</mark>](https://www.electronjs.org/docs/latest/api/structures/point)
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Mouse Move</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> <mark style="color:purple;background-color:purple;">**Windows**</mark> Fires when the mouse moves in the tray icon.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.tray.onMouseMove((data) => {})
```

**Arguments**

* `trayId` <mark style="color:green;">String</mark>
* `event` [<mark style="color:blue;">Electron.KeyboardEvent</mark>](https://www.electronjs.org/docs/latest/api/structures/keyboard-event)
* `position` [<mark style="color:blue;">Electron.Point</mark>](https://www.electronjs.org/docs/latest/api/structures/point)
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://deskifier.gitbook.io/deskifier/tray.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.