tauri-plugin-decoration 2.0.0

Native window controls, custom decorations, and Windows 11 Snap Layout for Tauri v2 apps.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# tauri-plugin-decoration


[![crates.io](https://img.shields.io/crates/v/tauri-plugin-decoration.svg)](https://crates.io/crates/tauri-plugin-decoration)

Native window controls, custom decorations, and Windows 11 Snap Layout for Tauri v2 apps.

## Features


- **Frameless window controls** — custom minimize/maximize/close buttons rendered as HTML, positioned over a transparent draggable titlebar area.
- **Windows 11 Snap Layout** — a native Win32 child HWND overlay returns `HTMAXBUTTON` from `WM_NCHITTEST`, triggering the OS-built Snap Layout flyout on hover. No keyboard or mouse simulation.
- **macOS traffic lights** — inset positioning for the native close/minimize/zoom buttons so they align with your app content. Also supports window transparency and window level control.
- **Linux system icons** — window control buttons use the current icon theme (via `linicon` + `dconf`).
- **Dark/light aware** — hover colors adapt to the user's color scheme preference.
- **Late-injection safe** — scripts check `document.readyState` so they work even when injected after `DOMContentLoaded`.

> [!NOTE]
> Windows 10: the overlay is created and positioned correctly, but the Snap Layout flyout is a Windows 11 feature. On Windows 10, hovering the maximize button still triggers maximize/restore — just no flyout.

## Usage


### 1. Add the plugin


```toml
# Cargo.toml

[dependencies]
tauri-plugin-decoration = "2"
```

### 2. Initialize in Rust


```rust
use tauri::Manager;
use tauri_plugin_decoration::WebviewWindowExt;

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_decoration::init())
        .setup(|app| {
            let main_window = app.get_webview_window("main").unwrap();
            main_window.create_overlay_titlebar().unwrap();

            // macOS-only helpers
            #[cfg(target_os = "macos")]
            {
                main_window.set_traffic_lights_inset(12.0, 16.0).unwrap();
                main_window.make_transparent().unwrap();
            }

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

### 3. Configure window


In `tauri.conf.json`, set `withGlobalTauri: true` and use frameless window options:

```json
{
  "app": {
    "withGlobalTauri": true,
    "windows": [
      {
        "titleBarStyle": "Overlay",
        "hiddenTitle": true,
        "decorations": false
      }
    ]
  }
}
```

### 4. Set permissions


In `src-tauri/capabilities/default.json`:

```json
"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"
```

### 5. Style the controls (optional)


The plugin injects buttons with these selectors:

```css
button#decoration-tb-minimize,
button#decoration-tb-maximize,
button#decoration-tb-close,
div[data-tauri-decoration-tb] {}
```

### 6. Interactive content in the titlebar area


The plugin creates a fixed-position overlay (`div[data-tauri-decoration-tb]`) at `z-index: 100` covering the top 32px of the window. This overlay handles window dragging and hosts the window control buttons. Any app content in that area will be behind the overlay and won't receive clicks.

If you need interactive elements in the titlebar area (dropdown menus, navigation tabs, etc.), position your content above the overlay and use `pointer-events` to let clicks fall through to the drag region in empty areas:

```css
.titlebar-content {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  z-index: 200;          /* above the decoration overlay (z-index: 100) */
  height: 32px;
  pointer-events: none;  /* let clicks fall through to the drag region */
}

.titlebar-content .interactive-element {
  pointer-events: auto;  /* re-enable clicks on menus, buttons, etc. */
}
```

## Example App


The repository includes a demo app at [`examples/tauri-app`](examples/tauri-app) showing a custom titlebar with dropdown menus.

```sh
pnpm install
pnpm example:dev
```

## Platform Support


| Feature | Windows | macOS | Linux |
|---|---|---|---|
| Custom window controls | Native HTML buttons | Native HTML buttons | System icon theme |
| Snap Layout flyout | Windows 11 only | — | — |
| Traffic light inset | — | Yes | — |
| Window transparency | — | Yes | — |
| Draggable titlebar | Yes | Yes | Yes |

## Credits


Original author: [clearlysid/tauri-plugin-decorum](https://github.com/clearlysid/tauri-plugin-decorum).
Snap Layout implementation inspired by [clarifei/tauri-plugin-frame](https://github.com/clarifei/tauri-plugin-frame) and [Hyph-M/tauri-plugin-snap-layout](https://github.com/Hyph-M/tauri-plugin-snap-layout).