tauri-plugin-snap-layout

Platform Support

Installation

Add the Rust crate to your Tauri app:

# src-tauri/Cargo.toml
[dependencies]
tauri-plugin-snap-layout = "1"

Add the JS/TS bindings to your frontend:

npm install tauri-plugin-snap-layout
# or
pnpm add tauri-plugin-snap-layout
# or your preferred package manager

Usage

1. Rust — Register the plugin and prepare required options.

Register the plugin in your src-tauri/src/lib.rs file:

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(
            tauri_plugin_snap_layout::init()
                .button_id("snap-btn")
                .build()
        )
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Set decorations to false in your src-tauri/tauri.conf.json file. This is done in the "windows" section.

"app": {
    "windows": [
      {
        "decorations": false
      }
    ],
  },

Add this permission to your src-tauri/capabilities/default.json.

{
  "permissions": ["snap-layout:default"]
}

2. Frontend — Add the button

Give your maximize/snap button the ID you configured in the rust setup stage:

<button id="snap-btn">Max</button>

No initialisation required. The plugin self-initialises via the injected script when the page loads.

If you're using a bundler and have the package installed:

import { changePadding, changeTarget, attach, detach, isAttached } from "tauri-plugin-snap-layout";

// Swap targetted button dynamically at runtime
changeTarget("new-button-id");

// Temporarily remove the Snap Zone by destroying the overlay area.
await detach();

// Re-enable the snap area, you can set a new target here as well.
attach("optional-new-target");

// Update layout padding offsets dynamically
changePadding( {} );

// Check if the native snap zone layout is currently active
isAttached();

changeTarget needs an existing ID to transfer to and will automatically update bounds based on the target.

changePadding will add or remove the area of the hover zone. If using negative padding it will have a minimum width/height of 1px. If this negative padding extends past the bounds of the button it will continue to move the hover area rather than stop at the bounds of the button.

Padding fields are set, not accumulated — each call overwrites the previous passed fields. all acts as a baseline that can combine with per-side values at render time. The example below results in 5 on the left and 3 on all other sides.

changePadding( {left: 2, right: 0, top: 0, bottom: 0, all:3} );

The options available are left, right, top, bottom, all.

Vanilla JavaScript Usage (Global Namespace)

If you are not using a module bundler, the plugin cleanly exposes its API under the single global window.snapLayout object.

Because this plugin targets native Windows 11 functionality, window.snapLayout will be undefined on unsupported operating systems (like macOS or Linux). To ensure your application remains safely cross-platform without throwing runtime errors, always use optional chaining (?.) when invoking the plugin:

// Swap targetted button dynamically at runtime
window.snapLayout?.changeTarget("new-button-id");

// Temporarily remove the Snap Zone by destroying the overlay area.
window.snapLayout?.detach();

// Re-enable the snap area, you can set a new target here as well.
window.snapLayout?.attach("your-titlebar-maximize-button-id");

// Update layout padding offsets dynamically
window.snapLayout?.changePadding( {} );

// Check if the native snap zone layout is currently active
window.snapLayout?.isAttached();

The same fields apply to changePadding as the bundled version above.

Optional Configuration

You can customize the bounding area, cursor, and debug mode via the Rust builder:

tauri_plugin_snap_layout::init()
    .button_id("snap-btn")
    .padding_left(0)
    .padding_right(0)
    .padding_top(0)
    .padding_bottom(0)
    .padding_all(0)
    // defaults to SnapCursor::Arrow if undefined
    .cursor(tauri_plugin_snap_layout::SnapCursor::Hand)
    // set true to show a debug overlay
    .display(false)
    .debug_color("rgba(255, 0, 0, 0.2)")
    .build()

CSS Hover State

Because the native overlay intercepts pointer events, :hover CSS will not fire on your button naturally. The plugin automatically mirrors any :hover rules it finds for your button into an .is-hovered class, which it applies when the native window detects cursor entry. You can also write .is-hovered styles directly:

#snap-btn:hover,
#snap-btn.is-hovered {
  background: rgba(255, 255, 255, 0.1);
}

Programmatic Window Management & Multi-Window Support

Multi-window applications are supported. Initialization scripts run globally across all webviews and the Rust backend uses explicit WebviewWindow instances, every open window isolates its own tracking loops and native Win32 child bounds. If you need to alter or toggle the snap zones in Rust, you can use the SnapExt extension trait on any window handle:

use tauri_plugin_snap_layout::SnapExt;

#[tauri::command]
fn manage_window_overlays(window: tauri::WebviewWindow) -> Result<(), tauri_plugin_snap_layout::Error> {
    // Remove the native Win32 child overlay on this window and stop tracking.
    window.snap().detach(&window)?;

    // Recreate overlay and resume tracking.
    window.snap().attach(&window)?;
    
    Ok(())
}

Troubleshooting

If you see something along these lines __SNAP_BUTTON_ID__ is not defined in the console, add the following to your vite.config.ts to prevent Vite from caching the plugin:

export default defineConfig({
  optimizeDeps: {
    exclude: ["tauri-plugin-snap-layout"],
  },
});

How it works

The plugin creates an invisible native Win32 child HWND positioned over your button. This child window returns HTMAXBUTTON from WM_NCHITTEST, which is the correct native path for triggering Windows 11's Snap Layout popup on frameless and borderless windows — no keyboard simulation or input injection.

Credits

Inspired by and originally derived from:

• tauri-plugin-frame by clarifei
• tauri-plugin-decorum by Siddharth

License

MIT — see LICENSE