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.0.0"

Add the JS/TS bindings to your frontend:

npm install tauri-plugin-snap-layout
# or
pnpm add tauri-plugin-snap-layout

Usage

1. Rust — Register the plugin

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");
}

2. Frontend — Add the button

Give your maximize/snap button the ID you configured in Rust:

<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, changeSnapTarget } from "tauri-plugin-snap-layout";
changeSnapTarget("new-button-id");
changePadding( {left: 0} )

changeSnapTarget 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. The padding applied is additive, so the below will result in 5 padding on the left, and 3 on all other sides.

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

If you need to call it from outside a module context (vanilla JS, inline scripts):

window.changeSnapTarget("new-button-id");
window.changePadding( {left: 0} )

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);
}

Permissions (Tauri v2)

If your app uses Tauri v2's strict permission system, ensure your app's capabilities allow the plugin to update bounds:

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

Programmatic Detach (Rust only)

If you need to programmatically destroy the native Win32 child window while the parent window remains open, you can use the SnapExt trait:

use tauri_plugin_snap_layout::SnapExt;

// Detaches the native snap zone from the specified window
window.snap().detach_snap_zone(&window)?;

Troubleshooting

If you see __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"],
  },
});

Credits

Inspired by and originally derived from:

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

License

MIT — see LICENSE