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 [Demo]

Install

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

[dependencies]
tauri-plugin-desktop-underlay = "0.1.1"

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

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:

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:

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

To operate on the current window:

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

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

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:

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. 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 before deciding whether to use this plugin, you may need to build the source code:

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

FAQ

See FAQ for the list of frequently asked questions. If these do not answer your question and you cannot find an answer in the issue tracker either, consider submitting a new issue.

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; this project is released under the MIT License.