Tauri Plugin Wallpaper

A Tauri plugin for advanced window positioning on Windows desktop

Features

Wallpaper Mode (Attach/Detach)

Embed your window behind desktop icons - perfect for creating animated wallpapers, desktop widgets, or background applications.

• attach - Places window behind desktop icons (wallpaper layer)
• detach - Restores window to normal behavior
• reset - Resets the desktop wallpaper

Pin Mode (Pin/Unpin)

Keep your window always on top and make it survive Win+D (Show Desktop) - perfect for overlay apps, sticky notes, or always-visible tools.

• pin - Window stays on top and ignores Show Desktop (Win+D)
• unpin - Restores normal window behavior

Platform Support

Windows Only - This plugin uses Win32 APIs for desktop integration.

Installation

# Rust
cargo add tauri-plugin-wallpaper

# JavaScript/TypeScript
npm install tauri-plugin-wallpaper

Usage

Rust

use tauri_plugin_wallpaper::{WallpaperExt, AttachRequest, PinRequest};

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_wallpaper::init())
        .setup(|app| {
            let handle = app.handle();

            // Wallpaper mode - window goes behind desktop icons
            handle.wallpaper().attach(AttachRequest::new("window_label"))?;
            handle.wallpaper().detach(DetachRequest::new("window_label"))?;
            handle.wallpaper().reset()?;

            // Pin mode - window stays on top, survives Win+D
            handle.wallpaper().pin(PinRequest::new("window_label"))?;
            handle.wallpaper().unpin(UnpinRequest::new("window_label"))?;

            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

JavaScript/TypeScript

import { attach, detach, reset, pin, unpin } from "tauri-plugin-wallpaper";

// Wallpaper mode - window goes behind desktop icons
await attach("window-label");  // or attach() for current window
await detach("window-label");
await reset();

// Pin mode - window stays on top, survives Win+D
await pin("window-label");     // or pin() for current window
await unpin("window-label");

Permissions

Add to your Tauri capabilities config:

{
  "permissions": [
    "wallpaper:default"
  ]
}

See permissions reference for granular permissions.

How It Works

Wallpaper Mode

Uses the Windows WorkerW technique to parent your window under the desktop's WorkerW layer, placing it behind icons but above the actual wallpaper.

Pin Mode

Subclasses the window procedure to intercept WM_WINDOWPOSCHANGING messages. When Win+D attempts to move the window to (-32000, -32000), the move is blocked, keeping the window visible.

Before You Depend on This

If you're building something beyond a hobby project, consider implementing the Win32 logic directly in your application rather than depending on this library. The core techniques are documented in the How It Works section and the source code is straightforward to adapt.

This gives you full control over the implementation and avoids dependency on a library that may not be actively maintained.

License

MIT