JavaScript Navigator windowControlsOverlay Property

What You’ll Learn

navigator.windowControlsOverlay is the experimental entry point to the Window Controls Overlay API for desktop Progressive Web Apps. Learn visible, getTitlebarAreaRect(), geometrychange, the manifest opt-in, five examples, and try-it labs.

Introduction

Installed desktop apps usually have a title bar with minimize / maximize / close buttons. Progressive Web Apps can look more “native” by drawing their own UI in that space — logo, tabs, search — while the OS still owns the window buttons.

That feature is the Window Controls Overlay. After you opt in from the web app manifest, navigator.windowControlsOverlay tells your page the geometry of the free title bar area so your custom chrome does not collide with the system controls.

Understanding the windowControlsOverlay Property

The property itself is only the entry point. The useful pieces live on the returned WindowControlsOverlay object.

• visible — boolean: is the window controls overlay visible?
• getTitlebarAreaRect() — returns a DOMRect for the title bar region.
• geometrychange — event when the title bar geometry (or visibility) changes.
• Secure context — HTTPS / localhost required.
• Desktop PWA focus — most useful after install + manifest opt-in.
• Limited support — feature-detect; keep a fallback layout.

📝 Syntax

General form of the property:

navigator.windowControlsOverlay

Value

• A WindowControlsOverlay object (when supported).

Common patterns

// MDN-style feature detect + title bar rect
if ("windowControlsOverlay" in navigator) {
  const rect = navigator.windowControlsOverlay.getTitlebarAreaRect();
  // Do something with the title bar area rectangle.
} else {
  // The Window Controls Overlay feature is not available.
}

// Listen for geometry changes (MDN):
if ("windowControlsOverlay" in navigator) {
  navigator.windowControlsOverlay.addEventListener("geometrychange", (event) => {
    if (event.visible) {
      const rect = event.titlebarAreaRect;
      // Layout custom title bar UI using rect
    }
  });
}

Manifest sketch (for installed desktop PWAs)

{
  "name": "My Desktop PWA",
  "display": "standalone",
  "display_override": ["window-controls-overlay"]
}

Examples Gallery

Examples follow MDN navigator.windowControlsOverlay patterns. Prefer Try It Yourself — in a normal browser tab the API is often missing or visible is false until you run an installed desktop PWA with the overlay enabled.

const lines = [
  "windowControlsOverlay: " +
    ("windowControlsOverlay" in navigator ? "available" : "missing"),
  "isSecureContext: " + window.isSecureContext
];
console.log(lines.join("\n"));

windowControlsOverlay: missing
isSecureContext: true
(or "available" in supporting desktop PWA environments)

if (!("windowControlsOverlay" in navigator)) {
  console.log("windowControlsOverlay not supported");
} else {
  console.log("visible: " + navigator.windowControlsOverlay.visible);
}

windowControlsOverlay not supported
(or visible: true / false in a supporting PWA)

if (!("windowControlsOverlay" in navigator)) {
  console.log("windowControlsOverlay not supported");
} else {
  const rect = navigator.windowControlsOverlay.getTitlebarAreaRect();
  console.log(
    "x=" + rect.x +
    " y=" + rect.y +
    " w=" + rect.width +
    " h=" + rect.height
  );
}

windowControlsOverlay not supported
(or x/y/w/h numbers when the overlay title bar area exists)

if (!("windowControlsOverlay" in navigator)) {
  console.log("windowControlsOverlay not supported");
} else {
  navigator.windowControlsOverlay.addEventListener("geometrychange", (event) => {
    if (event.visible) {
      const rect = event.titlebarAreaRect;
      console.log("geometrychange:", {
        x: rect.x,
        y: rect.y,
        width: rect.width,
        height: rect.height
      });
    } else {
      console.log("Overlay not visible — use fallback chrome");
    }
  });
  console.log("Listening for geometrychange");
}

windowControlsOverlay not supported
(or "Listening for geometrychange" then rect updates when resizing a supporting PWA)

function applyTitlebarLayout() {
  if (!("windowControlsOverlay" in navigator)) {
    return "API missing — keep a normal header";
  }
  const wco = navigator.windowControlsOverlay;
  if (!wco.visible) {
    return "Overlay not visible — keep a normal header";
  }
  const rect = wco.getTitlebarAreaRect();
  document.documentElement.style.setProperty("--titlebar-x", rect.x + "px");
  document.documentElement.style.setProperty("--titlebar-w", rect.width + "px");
  document.documentElement.style.setProperty("--titlebar-h", rect.height + "px");
  return "CSS vars set from title bar rect";
}

console.log(applyTitlebarLayout());

API missing — keep a normal header
(or "CSS vars set…" in a supporting overlay PWA)

🚀 Common Use Cases

• Custom PWA title bars — brand, tabs, or search in the title region.
• Desktop-first PWAs — make installed apps feel closer to native shells.
• Responsive chrome — reflow title UI on geometrychange.
• Safe insets — avoid drawing under minimize / maximize / close.
• Progressive enhancement — fall back to a normal in-page header.

📝 Notes

• Experimental & Limited availability — not Baseline; feature-detect always.
• Not Deprecated or Non-standard — Experimental banner only.
• Secure context required (HTTPS / localhost).
• Returns WindowControlsOverlay; main pieces are visible, getTitlebarAreaRect(), geometrychange.
• Related: webdriver, xr, wakeLock, Window.

💡 Best Practices