JavaScript Navigator windowControlsOverlay Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property
Decorative image with the word WINDOWCONTROLSOVERLAY

Definition

navigator.windowControlsOverlay is a read-only property that returns a WindowControlsOverlay object — title bar geometry for desktop Progressive Web Apps that opt into the Window Controls Overlay API (MDN).

Read the notes below before you rely on this property. Prefer feature detection when support is limited.

Syntax

Use navigator.windowControlsOverlay. Start with this line.

JavaScript
navigator.windowControlsOverlay
CallWhat it does
navigator.windowControlsOverlayPrimary signature.

Built into the browser. Read navigator.windowControlsOverlay on Navigator — no import required.

Library declarations
JavaScript
navigator.windowControlsOverlay

Parameters

ParameterDescription
Manifest opt-inRequired. display_override value
Desktop installRequired. Not active in a normal browser tab

Return Value

Return ValueDescription
*WindowControlsOverlay (EventTarget)

JavaScript Examples

Example 1 — Feature Detection

Check whether the API is exposed before reading geometry.

JavaScript
if ("windowControlsOverlay" in navigator) {
  console.log("Window Controls Overlay API available");
  console.log("visible:", navigator.windowControlsOverlay.visible);
} else {
  console.log("Window Controls Overlay not supported");
}

console.log("secure:", window.isSecureContext);
Try It Yourself

How It Works

  1. Ask the browser. The in operator checks for the property.
  2. Read visible. Often false in a normal tab even when the API exists.
  3. Check HTTPS. MDN requires a secure context in supporting browsers.
  4. Keep a fallback. Limited availability means many environments omit the API.

Example 2 — Read getTitlebarAreaRect()

Get the title bar area so you can place custom chrome safely.

JavaScript
if ("windowControlsOverlay" in navigator) {
  const wco = navigator.windowControlsOverlay;
  const r = wco.getTitlebarAreaRect();
  console.log("visible:", wco.visible);
  console.log("rect:", r.x, r.y, r.width, r.height);
} else {
  console.log("Window Controls Overlay not supported");
}
Try It Yourself

How It Works

  1. Detect first. Exit early when the API is missing.
  2. Call getTitlebarAreaRect(). Returns a DOMRect (no arguments).
  3. Use visible. Decide whether to show custom title-bar UI.
  4. Expect zeros. In a tab or unsupported mode the rect is often empty.

Example 3 — Listen for geometrychange

Update custom title UI when the window is resized or the overlay geometry changes.

JavaScript
if ("windowControlsOverlay" in navigator) {
  const wco = navigator.windowControlsOverlay;

  wco.addEventListener("geometrychange", (event) => {
    if (event.visible) {
      const r = event.titlebarAreaRect;
      console.log("title bar:", r.x, r.y, r.width, r.height);
      // position custom title UI inside that rect
    } else {
      console.log("overlay not visible — use fallback header");
    }
  });

  console.log("listening for geometrychange");
} else {
  console.log("Window Controls Overlay not supported");
}
Try It Yourself

How It Works

  1. Subscribe once. geometrychange reports layout changes for the title bar area.
  2. Read the event. Use event.visible and event.titlebarAreaRect (MDN).
  3. Branch on visibility. Hide custom chrome when the overlay is off.
  4. Keep updates light. Reposition title UI — avoid heavy work in the handler.
Compatibility

Browser Support

Navigator.windowControlsOverlay is part of the Window Controls Overlay API. MDN marks WindowControlsOverlay Experimental and Limited availability (not Baseline). Requires a secure context and a desktop installed PWA with the manifest opt-in.

✓ Experimental · Limited availability

Navigator.windowControlsOverlay

Best support in Chromium desktop browsers from version 105 (Chrome, Edge, Opera). Missing in Firefox, Safari, and mobile. Always feature-detect.

Limited Not Baseline
Google Chrome 105+ desktop (secure)
Yes
Microsoft Edge 105+ desktop (secure)
Yes
Opera 91+ desktop (Chromium)
Yes
Mozilla Firefox Not supported
No
Apple Safari Not supported
No
Internet Explorer Not supported
No
windowControlsOverlay Chromium 105+

Bottom line: Ship behind a feature detect + fallback header. See the MDN windowControlsOverlay reference.

Frequently Asked Questions

A WindowControlsOverlay object. In desktop Progressive Web Apps that opt into Window Controls Overlay, it exposes title bar geometry (getTitlebarAreaRect), a visible flag, and a geometrychange event.
MDN marks the WindowControlsOverlay interface Experimental and Limited availability (not Baseline). It is not Deprecated or Non-standard. Always feature-detect and keep a fallback title bar layout.
Yes. MDN lists it as a secure-context feature (HTTPS or localhost) in supporting browsers.
In your web app manifest, set display_override to include window-controls-overlay, then install the PWA on a desktop OS. That hides the default title bar and gives the app the full window area.
A method that returns a DOMRect for the title bar area so you can place custom UI (logo, tabs, search) without covering the system window controls.
Usually the overlay is not active outside an installed desktop PWA with the manifest opt-in. visible is often false in a tab. Always feature-detect and design a fallback.

Next: xr

Learn how navigator.xr accesses the WebXR Device API.

xr tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

10 people found this page helpful

JavaScript Navigator webdriver Property JavaScript Navigator xr Property