No Login Data Private Local Save

Window Controls Overlay Demo - Online PWA Title Bar Customization

5
0
0
0

Window Controls Overlay Demo

Explore how PWA title bar customization works with the Window Controls Overlay API. Visualize safe zones, environment variables, and build immersive app-like experiences.

📱 My PWA App
Dashboard
Real-time analytics
Messages
3 new notifications
Settings
App preferences

Titlebar Height44px
env(titlebar-area-x) = 0px
env(titlebar-area-y) = 0px
env(titlebar-area-width) = 820px
env(titlebar-area-height) = 44px
* Values update dynamically based on platform & settings

{
  "name": "My PWA App",
  "short_name": "PWA",
  "start_url": "/",
  "display": "standalone",
  "display_override": ["window-controls-overlay"],
  "theme_color": "#667eea",
  "background_color": "#ffffff",
  "icons": [
    {
      "src": "icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}
🔑 Key: display_override: ["window-controls-overlay"] enables the feature. Falls back gracefully if unsupported.
/* Detect WCO mode */
@media (display-mode: window-controls-overlay) {
  /* Styles specific to WCO mode */
  .titlebar {
    position: fixed;
    left: env(titlebar-area-x, 0);
    top: env(titlebar-area-y, 0);
    width: env(titlebar-area-width, 100%);
    height: env(titlebar-area-height, 40px);
    background: #1a1a2e;
    color: #fff;
    display: flex;
    align-items: center;
    padding: 0 12px;
  }
}

/* Drag region - titlebar background */
.titlebar {
  -webkit-app-region: drag;
  app-region: drag;
}

/* Interactive elements need no-drag */
.titlebar button,
.titlebar input {
  -webkit-app-region: no-drag;
  app-region: no-drag;
}
// Check if WCO is available
if ('windowControlsOverlay' in navigator) {
  const wco = navigator.windowControlsOverlay;
  
  console.log('WCO visible:', wco.visible);
  
  // Listen for geometry changes
  wco.addEventListener('geometrychange', () => {
    if (wco.visible) {
      console.log('Titlebar area changed!');
      // CSS env() variables update automatically
    }
  });
}

// CSS env variables available in WCO mode:
// env(titlebar-area-x)      - X offset of titlebar
// env(titlebar-area-y)      - Y offset of titlebar
// env(titlebar-area-width)  - Full titlebar width
// env(titlebar-area-height) - Titlebar height
<!-- Titlebar with safe content placement -->
<div class="titlebar">
  <div class="titlebar-content">
    <span class="app-logo">📱</span>
    <span class="app-name">My PWA</span>
  </div>
  <input type="search" placeholder="Search...">
</div>

What is Window Controls Overlay (WCO)?
Window Controls Overlay is a Progressive Web App (PWA) feature that allows web applications to use the entire window surface area, including the title bar region where window control buttons (minimize, maximize, close) reside. Instead of the browser rendering a default title bar, the PWA can draw custom content in that space, creating a more native-like, immersive experience. It's enabled via display_override: ["window-controls-overlay"] in the web app manifest.
How do CSS environment variables work with WCO?
When WCO is active, the browser exposes four CSS environment variables that describe the title bar area geometry:

• env(titlebar-area-x) — X coordinate of the title bar area (usually 0)
• env(titlebar-area-y) — Y coordinate of the title bar area (usually 0)
• env(titlebar-area-width) — Full width of the title bar
• env(titlebar-area-height) — Height of the title bar (varies by OS: ~29px Windows 10, ~32px Windows 11, ~22-28px macOS)

These let you position custom content safely without overlapping the window control buttons. Always provide fallback values: env(titlebar-area-height, 40px).
Which browsers support Window Controls Overlay?
As of 2025, Window Controls Overlay is supported in:
• Google Chrome 102+ (desktop)
• Microsoft Edge 102+ (desktop)
• Opera 88+ (desktop)
• Brave (Chromium-based, desktop)

It is not supported in Firefox or Safari. On mobile platforms, the feature has no effect since mobile apps don't have traditional window controls. The API degrades gracefully — unsupported browsers simply ignore display_override and use the standard display mode.
What is the drag region and how do I handle it?
In WCO mode, the title bar area becomes a drag region by default, meaning users can click and drag to move the window. Use CSS to control this:

• -webkit-app-region: drag; — Makes an element draggable (for the titlebar background)
• -webkit-app-region: no-drag; — Makes interactive elements (buttons, inputs) clickable

Important: Any interactive element inside the titlebar (search boxes, buttons, links) must have no-drag set, otherwise clicks won't register. The window control buttons are automatically handled by the OS.
How does WCO differ between Windows and macOS?
The key difference is the position of window control buttons:

• Windows: Control buttons (minimize, maximize, close) are on the top-right. Place custom content on the left or center of the titlebar.
• macOS: Traffic light buttons (close, minimize, maximize) are on the top-left. Place custom content in the center or right of the titlebar.

The env(titlebar-area-*) variables automatically account for these differences, so using them correctly ensures your content never overlaps the controls regardless of platform. Always test on both operating systems.
Can I detect WCO mode in JavaScript?
Yes! Use navigator.windowControlsOverlay:

• navigator.windowControlsOverlay.visible — Returns true if WCO is currently active
• navigator.windowControlsOverlay.addEventListener('geometrychange', callback) — Fires when the titlebar area changes (e.g., when the user resizes the window or toggles WCO)

You can also use the CSS media query: @media (display-mode: window-controls-overlay) { ... } to apply styles conditionally.
What are the best practices for designing a WCO titlebar?
Best practices:
1. Keep it simple — The titlebar is small (30-44px). Prioritize essential content like app name, search, or primary navigation.
2. Respect the safe zone — Always use env() variables to avoid overlapping control buttons.
3. Provide fallback styles — Use fallback values in env() for when WCO is not active.
4. Test contrast — Titlebar content should be clearly visible against your chosen background.
5. Don't overcrowd — Leave breathing room. The titlebar isn't a replacement for the main navigation.
6. Handle drag regions correctly — Ensure interactive elements use no-drag.
Is Window Controls Overlay the same as a custom title bar?
Not exactly. A custom title bar (using frame: "none" in Electron or similar) completely removes the native window controls and requires you to re-implement minimize/maximize/close functionality from scratch. Window Controls Overlay is different — it keeps the native window controls but allows you to draw content in the remaining title bar space. This is safer, more accessible, and respects OS conventions while still giving you creative freedom.