tauri-plugin-desktop-underlay 0.1.0

Tauri plugin for attaching a window to desktop, below icons and above wallpaper.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

# PLUGIN-DESKTOP-UNDERLAY

[![tauri](https://img.shields.io/badge/Tauri%20Plugin-4A4A55?style=flat-square&logo=tauri&logoColor=00D1B2)](https://v2.tauri.app/)
[![license](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay/tree/main/LICENSE)
[![npm](https://img.shields.io/npm/v/tauri-plugin-desktop-underlay-api?color=blue&style=flat-square)](https://www.npmjs.com/package/tauri-plugin-desktop-underlay-api)
[![npm](https://img.shields.io/npm/d18m/tauri-plugin-desktop-underlay-api?color=blue&style=flat-square)](https://www.npmjs.com/package/tauri-plugin-desktop-underlay-api)
[![crates.io](https://img.shields.io/crates/v/tauri-plugin-desktop-underlay.svg?color=blue&style=flat-square)](https://crates.io/crates/tauri-plugin-desktop-underlay)
[![crates.io](https://img.shields.io/crates/dr/tauri-plugin-desktop-underlay?color=blue&style=flat-square)](https://crates.io/crates/tauri-plugin-desktop-underlay)
[![docs.rs](https://img.shields.io/docsrs/tauri-plugin-desktop-underlay?color=blue&style=flat-square)](https://docs.rs/tauri-plugin-desktop-underlay)

Tauri plugin for attaching a window to desktop, below icons and above wallpaper, referred to as a **desktop underlay**.

- **Linux:** Not tested, thus not guaranteed to work.
- **MacOS:** ✅
- **Windows:** ✅

## Examples

- [Desktop Clock](https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay/tree/main/examples/desktop-clock) [[Demo](https://github.com/user-attachments/assets/894a5afb-269e-4158-af13-add266a69576)]

## Install

Install the desktop underlay plugin by adding the following to your `Cargo.toml` file:

```toml
[dependencies]
tauri-plugin-desktop-underlay = "0.1.0"
```

You can install the JavaScript guest bindings using your preferred JavaScript package manager:

```bash
npm install tauri-plugin-desktop-underlay-api # or
yarn add tauri-plugin-desktop-underlay-api # or
pnpm add tauri-plugin-desktop-underlay-api
```

## Usage

First you need to register the core plugin with Tauri:

```rust
tauri::Builder::default()
    // Initialize the desktop-underlay plugin
    .plugin(tauri_plugin_desktop_underlay::init())
    .run(tauri::generate_context!())
    .unwrap();
```

Afterwards all the plugin's APIs are available through the JavaScript guest bindings:

```typescript
import {
  setDesktopUnderlay,
  isDesktopUnderlay,
  toggleDesktopUnderlay,
} from "tauri-plugin-desktop-underlay-api";
```

To operate on the current window:

```typescript
const isUnderlay = await isDesktopUnderlay();
await setDesktopUnderlay(true);
await setDesktopUnderlay(false);
const nowIsUnderlay = await toggleDesktopUnderlay();
```

To operate on another window (say, with label `wallpaper`):

```typescript
const isUnderlay = await isDesktopUnderlay("wallpaper");
await setDesktopUnderlay(true, "wallpaper");
await setDesktopUnderlay(false, "wallpaper");
const nowIsUnderlay = await toggleDesktopUnderlay("wallpaper");
```

If you only intend on using the APIs from Rust code, you can import the `DesktopUnderlayExt` extension on windows and webview windows:

```rust
use tauri_plugin_desktop_underlay::DesktopUnderlayExt;

let main_window = app.get_webview_window("main").unwrap();
let is_underlay = main_window.is_desktop_underlay();
let _ = main_window.set_desktop_underlay(true);
let _ = main_window.set_desktop_underlay(false);
let now_is_underlay = main_window.toggle_desktop_underlay();
```

## Permissions

See [permissions reference](https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay/tree/main/permissions/autogenerated/reference.md). You do not need to add permissions if you are not using the JavaScript guest bindings.

## Build from Source

If you want to try a local build, or you want to try the [examples](#examples) before deciding whether to use this plugin, you may need to build the source code:

```bash
git clone https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay.git
pnpm install
pnpm build
```

## FAQ

See [FAQ](https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay/tree/main/FAQ.md) for the list of frequently asked questions. If these do not answer your question and you cannot find an answer in the [issue tracker](https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay/issues) either, consider [submitting a new issue](https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay/issues/new).

## Contributing

Feel free to open issues to report bugs or request features and improvements. Since I majorly develop on Windows, there could be many problems on Linux and macOS that I am not aware of. Pull requests are also welcome, though for larger changes it would be generally better to open an issue for discussion first.

## License

Copyright (c) 2024-2025 Yao Xiao [@Charlie-XIAO](https://github.com/Charlie-XIAO); this project is released under the [MIT License](https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay/tree/main/LICENSE).