Dropping the OS Title Bar in Tauri: What decorations: false Actually Costs You

You want your Tauri app to look like a real product, not a web page trapped inside an OS window frame. The obvious move is to set decorations to false in tauri.conf.json and render your own title bar in HTML. That one-line change is easy. The consequences are not, and they differ sharply per platform. This post walks through what the setting actually does, a working configuration, and the platform-specific work you inherit the moment you flip it.

What the decorations flag really controls

Every desktop window has a "non-client area" — the title bar, borders, and resize handles the operating system draws around your content. When you disable decorations, Tauri asks the OS not to draw that area, so your webview becomes responsible for everything the user sees, including the frame.

The key insight: the OS still owns window behavior (dragging, resizing, minimizing), but it no longer owns window appearance. You must bridge the two. Tauri exposes this bridge through the data-tauri-drag-region HTML attribute and window APIs like startDragging() and setResizable().

A minimal working setup

In tauri.conf.json (Tauri 2.x layout):

{
  "app": {
    "windows": [
      {
        "label": "main",
        "decorations": false,
        "transparent": false,
        "resizable": true
      }
    ]
  }
}

Then in your markup, build the replacement title bar:

<header data-tauri-drag-region class="titlebar">
  <span data-tauri-drag-region>My App</span>
  <div class="controls">
    <button id="min">–</button>
    <button id="close">×</button>
  </div>
</header>

Wire the buttons to the window API (run in your frontend, no special OS permissions needed):

import { getCurrentWindow } from '@tauri-apps/api/window';
const win = getCurrentWindow();
document.getElementById('min').onclick = () => win.minimize();
document.getElementById('close').onclick = () => win.close();

Two details matter here. First, elements marked data-tauri-drag-region drag the window — but interactive children (your buttons) must not have that attribute, or clicks get swallowed as drags. Second, on Windows you lose the native double-click-to-maximize on the title bar, so add your own double-click handler calling win.toggleMaximize() if you want parity with native apps.

Platform differences you cannot ignore

Windows is the most forgiving visually but the trickiest behaviorally. With decorations off, snap-assist (dragging to screen edges) and native resize-from-border can degrade depending on version and configuration. Tauri's runtime forwards the relevant non-client hit-testing for you in most cases, but you should verify edge-resize and Aero Snap on your target Windows version — this is where most bug reports come from.

macOS takes a different path. Rather than fully removing the frame, you typically combine decorations: false (or keep decorations and use titleBarStyle options like "hidden" or "overlay") so traffic-light buttons remain while your content extends into the title area. Fully removing decorations on macOS also removes the traffic lights, which users expect — plan to either keep them via titleBarStyle or render replacements.

Linux is the wildcard. Behavior depends on the window manager and compositor. Environments using client-side decorations (GNOME/Mutter, KDE/KWin) generally handle decorations: false cleanly. On some X11 setups or tiling window managers you may see leftover borders, broken focus behavior, or conflicts with the WM's own keyboard-driven window controls. There is no single config that is correct everywhere — test on at least one GNOME and one KDE target.

The trade-off

What you gain: full visual control, brand consistency, and the ability to put real UI (search boxes, tabs) in the title area. What you lose: a pile of free OS behavior — native shadows, snap layouts, accessibility hints about the window frame, and consistent behavior across Linux WMs. You also take on maintenance across Tauri versions: the configuration schema and defaults changed between Tauri 1.x and 2.0, so confirm which major version your app targets before copying config snippets from older tutorials.

How to verify it worked

After tauri build, open the bundled config and confirm the decorations value survived. Then verify per platform: on Windows, check that edge resizing and snap still work and that no border flashes on launch; on macOS, use Xcode's Accessibility Inspector to confirm the title bar region behaves as expected; on Linux, run xwininfo against your window and compare with a decorations: true build as a baseline. If you see double frames, a missing drag region, or dead resize edges, the fix is almost always in the drag-region markup or the window manager — not in Rust code.

The actionable takeaway: treat decorations: false as a feature you build, not a flag you set. Budget a day for the custom title bar UI and another for per-platform behavior testing, and you'll avoid the "why can't users resize my app" support tickets.