Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 39 ยท Windows and Menus

Custom Title Bars, Transparency and Window Effects

Build a custom title bar in Tauri: turn off decorations, add data-tauri-drag-region, wire minimize, maximize and close buttons, plus transparent windows, shadows and platform quirks.

The native title bar is reliable, but many apps want their own look: a title bar that merges with the toolbar, a frameless palette, a rounded floating widget. Tauri lets you remove the native frame and draw your own with HTML and CSS. The price is that you now own behaviors the system gave you for free: dragging, buttons and resizing.

Step 1: remove the decorations

JSON
{
  "app": {
    "windows": [
      { "label": "main", "title": "Notes", "decorations": false, "width": 960, "height": 640 }
    ]
  }
}

With decorations: false the window has no title bar and no buttons. You can also pass .decorations(false) to a WebviewWindowBuilder.

Step 2: a draggable region

Add the data-tauri-drag-region attribute to an element and dragging it moves the window. Double-clicking toggles maximize.

HTML
<div class="titlebar" data-tauri-drag-region>
  <span class="title" data-tauri-drag-region>Notes</span>
  <div class="buttons">
    <button id="min" aria-label="Minimize">โ€”</button>
    <button id="max" aria-label="Maximize">โ–ข</button>
    <button id="close" aria-label="Close">โœ•</button>
  </div>
</div>
CSS
.titlebar {
  height: 36px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  background: #1e1e2e;
  color: #cdd6f4;
  user-select: none;
}
.buttons button { width: 46px; height: 36px; border: 0; background: transparent; color: inherit; }
.buttons button:hover { background: rgb(255 255 255 / 0.1); }
#close:hover { background: #e81123; }

The attribute applies to the element it is on, not its children: clicks on a child that lacks the attribute do not drag. That is why the <span> carries it too. Buttons must not have it, or they could not be clicked.

Step 3: wire the buttons

TypeScript
import { getCurrentWindow } from "@tauri-apps/api/window";

const win = getCurrentWindow();
document.getElementById("min")!.addEventListener("click", () => win.minimize());
document.getElementById("max")!.addEventListener("click", () => win.toggleMaximize());
document.getElementById("close")!.addEventListener("click", () => win.close());

The window permissions must allow them: core:window:allow-minimize, core:window:allow-toggle-maximize, core:window:allow-close and core:window:allow-start-dragging. Forgetting allow-start-dragging is the most common reason a custom title bar "does not drag".

Things you must handle yourself

  • Resizing. Without a frame, some platforms still provide invisible resize borders for resizable windows, others do not. Test dragging window edges on each platform.
  • Window controls placement. macOS users expect buttons on the left, Windows users on the right. Detect the platform (for example with the OS plugin) and arrange accordingly.
  • Maximize icon state. Listen to onResized and swap the maximize and restore icons using isMaximized().
  • Snap layouts and system gestures may be unavailable on Windows with a fully custom frame.

macOS: overlay title bar

On macOS you can keep the system traffic-light buttons and let your content draw underneath the title bar, getting the polished look with little work:

JSON
{ "label": "main", "titleBarStyle": "Overlay", "hiddenTitle": true }

Reserve space on the left of your header (about 70 px) so your own content does not collide with the buttons.

Transparency and effects

A transparent window draws only what your page paints. Set transparent: true on the window and a transparent page background:

JSON
{ "label": "widget", "decorations": false, "transparent": true, "width": 320, "height": 160, "alwaysOnTop": true }
CSS
html, body { background: transparent; }
.card { border-radius: 16px; background: rgb(30 30 46 / 0.85); backdrop-filter: blur(12px); }

Notes:

  • On macOS transparency needs the macos-private-api Cargo feature and config flag, which makes the app ineligible for the Mac App Store. Check the current docs before relying on it.
  • Native effects such as acrylic, mica or vibrancy are exposed through window.set_effects(...) with the Effect types on supported platforms.
  • Windows can have a drop shadow even when undecorated: window.set_shadow(true).
  • alwaysOnTop, skipTaskbar, focus: false and shadow are handy for widgets and overlays.

Click-through and fixed layouts

window.set_ignore_cursor_events(true) makes a window click-through, useful for overlays. Combine with alwaysOnTop and use it sparingly; users need a way to dismiss it, such as a tray item or shortcut.

Try it: a title bar model (stand-in)

This stand-in models the state a custom title bar must keep: the window state, the button actions, and the maximize icon that changes with state.

Node.js Stand-in: custom title bar state

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Try it: the drag region rule (live HTML)

Real windows cannot drag in the browser, but the rule about which element receives the attribute is easy to see. This live example highlights the draggable parts of a title bar.

Which parts of the bar are draggable?

Accessibility note

A custom title bar must keep buttons reachable with the keyboard and labelled for screen readers (aria-label, as above). If you replace the native frame, you also take over focus order, so test with the Tab key.

Next: System tray icons.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does data-tauri-drag-region do?

    Mouse down on that element starts window dragging.
  2. 2. Why does the attribute not apply to child elements automatically?

    Each draggable element needs the attribute, while buttons must not have it.
  3. 3. A custom title bar that will not drag is most likely missing which permission?

    Dragging uses the start-dragging window permission.
  4. 4. What must you handle yourself once decorations are off?

    The native frame provided those behaviors; a custom bar takes them over.

Summary

  • Set decorations: false and draw your own title bar in HTML.
  • Mark draggable elements with data-tauri-drag-region; keep buttons clickable.
  • Wire minimize, maximize and close with getCurrentWindow() and grant the permissions.
  • Transparency, shadows and effects depend on platform and config.
  • Take care of resizing, platform button placement and accessibility.

Next: System tray icons