Window Controls Overlay turns desktop PWAs into true native windows

Why this matters for desktop PWAs

Most desktop PWAs still look like browser windows with a thin title bar. The Window Controls Overlay API changes that by letting your app draw into the full title bar region while the OS keeps its minimize, maximize, and close buttons.

This matters because users expect installed apps to feel native. A PWA that respects the desktop environment builds immediate trust and reduces the "this is just a website" perception.

How to implement Window Controls Overlay

Add the display-override field in your web app manifest:

{
  "display_override": ["window-controls-overlay"]
}

Then use the Window Controls Overlay API in JavaScript:

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', (e) => {
    const { titlebarAreaRect } = e;
    // Position your custom header content within titlebarAreaRect
  });
}

Checklist for production desktop PWAs

• [ ] Set display_override to include "window-controls-overlay"
• [ ] Test on Windows, macOS, and Linux (Chromium-based)
• [ ] Respect system theme for title bar color via CSS color-scheme
• [ ] Provide fallback for browsers without the API
• [ ] Ensure draggable regions work correctly with -webkit-app-region: drag
• [ ] Keep close/minimize buttons accessible and correctly positioned

Sources

• MDN Window Controls Overlay API
• Chrome Developer Docs on display-override
• W3C Web App Manifest spec