DOCSEARCHbyAlgolia
Submit Docs

tauri-plugin-decorum

repository·main·Indexed 43 days ago

https://github.com/clearlysid/tauri-plugin-decorum

Opinionated window decoration controls for Tauri v2 apps. It provides highly customizable window decorations, allowing developers to create integrated titlebars that retain native features like Windows Snap Layouts and macOS traffic light insets. Version 1.1.1 includes methods for creating overlay titlebars, setting macOS traffic light insets, and triggering the Windows snap overlay via the show_snap_overlay command.

Tokens
2.2K
Snippets
10
Records
11
Agent score
55%

What's inside tauri-plugin-decorum

  3. Configure permissions for tauri-plugin-decorum

    main

    To allow the plugin to control window decorations and features, you must add specific permissions to your window capabilities in src-tauri/capabilities/default.json. Additionally, ensure that withGlobalTauri is set to true in your tauri.conf.json.

    Required permissions:

    • core:window:allow-close
    • core:window:allow-center
    • core:window:allow-minimize
    • core:window:allow-maximize
    • core:window:allow-set-size
    • core:window:allow-set-focus
    • core:window:allow-is-maximized
    • core:window:allow-start-dragging
    • core:window:allow-toggle-maximize
    • decorum:allow-show-snap-overlay
    "core:window:allow-close",
"core:window:allow-center",
"core:window:allow-minimize",
"core:window:allow-maximize",
"core:window:allow-set-size",
"core:window:allow-set-focus",
"core:window:allow-is-maximized",
"core:window:allow-start-dragging",
"core:window:allow-toggle-maximize",
"decorum:allow-show-snap-overlay"

  4. Initialize the decorum plugin

    main

    To use the decorum plugin in your Tauri application, call the init() function within your tauri::Builder. This sets up the plugin's command handlers and event listeners.

    use tauri_plugin_decorum::init;

fn main() {
    tauri::Builder::default()
        .plugin(init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

  5. Use tauri-plugin-decorum in Rust

    main

    Initialize the plugin in your main.rs using .plugin(tauri_plugin_decorum::init()). The plugin provides the WebviewWindowExt trait, which adds helper methods to WebviewWindow instances.

    Key methods include:

    • create_overlay_titlebar(): Creates a custom titlebar. On Windows, this hides default decorations and creates custom controls. On macOS, it requires hiddenTitle: true and titleBarStyle: overlay in your window configuration.
    • set_traffic_lights_inset(x, y): (macOS only) Sets a custom inset for the traffic lights.
    • make_transparent(): (macOS only) Makes the window transparent without requiring private APIs.
    • set_window_level(level): (macOS only) Sets the window level (e.g., using NSWindowLevel values).
    use tauri::Manager;
use tauri_plugin_decorum::WebviewWindowExt; // adds helper methods to WebviewWindow

fn main() {
	tauri::Builder::default()
		.plugin(tauri_plugin_decorum::init()) // initialize the decorum plugin
		.setup(|app| {
			// Create a custom titlebar for main window
			let main_window = app.get_webview_window("main").unwrap();
			main_window.create_overlay_titlebar().unwrap();

			#[cfg(target_os = "macos")] {
				// Set a custom inset to the traffic lights
				main_window.set_traffic_lights_inset(12.0, 16.0).unwrap();

				// Make window transparent
				main_window.make_transparent().unwrap();

				// Set window level
				main_window.set_window_level(25).unwrap();
			}

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

  6. Style window controls with CSS

    main

    You can style the custom window controls (minimize, maximize, close) and the titlebar container using the following CSS selectors:

    • button.decorum-tb-btn
    • button#decorum-tb-minimize
    • button#decorum-tb-maximize
    • button#decorum-tb-close
    • div[data-tauri-decorum-tb]
    button.decorum-tb-btn,
button#decorum-tb-minimize,
button#decorum-tb-maximize,
button#decorum-tb-close,
div[data-tauri-decorum-tb], {}

  7. Configure permissions for show_snap_overlay

    main

    The tauri-plugin-decorum plugin uses specific permission identifiers to control access to the show_snap_overlay command. You must grant these permissions in your Tauri application's capability configuration to allow or restrict the overlay functionality.

    Use the following identifiers:

    • decorum:allow-show-snap-overlay: Enables the show_snap_overlay command without requiring any pre-configured scope.
    • decorum:deny-show-snap-overlay: Denies the show_snap_overlay command without any pre-configured scope.
    | Identifier | Description |
| :--- | :--- |
| `decorum:allow-show-snap-overlay` | Enables the show_snap_overlay command without any pre-configured scope. |
| `decorum:deny-show-snap-overlay` | Denies the show_snap_overlay command without any pre-configured scope. |

  8. Show the Snap Overlay via show_snap_overlay

    main

    The show_snap_overlay command triggers a Windows-specific keyboard sequence to open the Snap Layouts overlay. On Windows, it simulates pressing Win + Z followed by a short delay and an Alt key press to hide UI elements (like numbers) that might appear during the snap process. This command is only functional when targeting the Windows operating system.

    // This command is invoked from the Tauri frontend
await invoke('show_snap_overlay');

  9. Show the snap overlay with show_snap_overlay()

    main

    Use the show_snap_overlay function to trigger the plugin's snap overlay via the Tauri command system. This function is an asynchronous wrapper around the plugin:decorum|show_snap_overlay command.

    import { show_snap_overlay } from './path-to-guest-js/index';

async function triggerOverlay() {
  await show_snap_overlay();
}

  10. Create a custom overlay titlebar

    main

    The create_overlay_titlebar() method removes the default system titlebar and injects a custom draggable area and window controls into your webview.

    • Windows: Removes decorations and injects custom window controls via JavaScript.
    • Linux: Injects custom controls using system icons (via linicon) and respects GNOME button layout preferences if available.
    • macOS: This method is part of the extension trait but primarily focuses on the draggable area logic.

    Note: This method listens for the decorum-page-load event to inject the necessary JavaScript once the page is ready.

    // Assuming `window` is a `WebviewWindow` instance
window.create_overlay_titlebar().unwrap();

  11. Configure permissions for the show_snap_overlay command

    main

    To use the show_snap_overlay command in your Tauri application, you must explicitly grant permission in your application's capability/permission configuration.

    Use the allow-show-snap-overlay identifier to enable the command. This permission allows the command to execute without any pre-configured scope.

    [[permission]]
identifier = "allow-show-snap-overlay"
description = "Enables the show_snap_overlay command without any pre-configured scope."
commands.allow = ["show_snap_overlay"]