Use the title bar area next to the window controls to make your PWA feel more like an app.
If you remember my article Make your PWA feel more like an app, you may recall how I mentioned customizing the title bar of your app as a strategy for creating a more app-like experience. Here is an example of how this can look showing the macOS Podcasts app.
Now you may be tempted to object by saying that Podcasts is a platform-specific macOS app that does not run in a browser and therefore can do what it wants without having to play by the browser's rules. True, but the good news is that the Window Controls Overlay feature, which is the topic of this very article, soon lets you create similar user interfaces for your PWA.
Window Controls Overlay components
Window Controls Overlay consists of four sub-features:
- The
"window-controls-overlay"
value for the"display_override"
field in the web app manifest. - The CSS environment variables
titlebar-area-x
,titlebar-area-y
,titlebar-area-width
, andtitlebar-area-height
. - The standardization of the previously proprietary CSS property
-webkit-app-region
as theapp-region
property to define draggable regions in web content. - A mechanism to query for and work around the window controls region via the
windowControlsOverlay
member ofwindow.navigator
.
What is Window Controls Overlay
The title bar area refers to the space to the left or right of the window controls (that is, the buttons to minimize, maximize, close, etc.) and often contains the title of the application. Window Controls Overlay lets progressive web applications (PWAs) provide a more app-like feel by swapping the existing full-width title bar for a small overlay containing the window controls. This allows developers to place custom content in what was previously the browser-controlled title bar area.
Current status
Step | Status |
---|---|
1. Create explainer | Complete |
2. Create initial draft of specification | Complete |
3. Gather feedback & iterate on design | In progress |
4. Origin trial | Complete |
5. Launch | Complete (in Chromium 104) |
How to use Window Controls Overlay
Adding window-controls-overlay
to the web app manifest
A progressive web app can opt-in to the window controls overlay by adding
"window-controls-overlay"
as the primary "display_override"
member in the web app manifest:
{
"display_override": ["window-controls-overlay"]
}
The window controls overlay will be visible only when all of the following conditions are satisfied:
- The app is not opened in the browser, but in a separate PWA window.
- The manifest includes
"display_override": ["window-controls-overlay"]
. (Other values are allowed thereafter.) - The PWA is running on a desktop operating system.
- The current origin matches the origin for which the PWA was installed.
The result of this is an empty title bar area with the regular window controls on the left or the right, depending on the operating system.
Moving content into the title bar
Now that there is space in the title bar, you can move something there. For this article, I built a Wikimedia Featured Content PWA. A useful feature for this app may be a search for words in the article titles. The HTML for the search feature looks like this:
<div class="search">
<img src="logo.svg" alt="Wikimedia logo." width="32" height="32" />
<label>
<input type="search" />
Search for words in articles
</label>
</div>
To move this div
up into the title bar, some CSS is needed:
.search {
/* Make sure the `div` stays there, even when scrolling. */
position: fixed;
/**
* Gradient, because why not. Endless opportunities.
* The gradient ends in `#36c`, which happens to be the app's
* `<meta name="theme-color" content="#36c">`.
*/
background-image: linear-gradient(90deg, #36c, #131313, 33%, #36c);
/* Use the environment variable for the left anchoring with a fallback. */
left: env(titlebar-area-x, 0);
/* Use the environment variable for the top anchoring with a fallback. */
top: env(titlebar-area-y, 0);
/* Use the environment variable for setting the width with a fallback. */
width: env(titlebar-area-width, 100%);
/* Use the environment variable for setting the height with a fallback. */
height: env(titlebar-area-height, 33px);
}
You can see the effect of this code in the screenshot below. The title bar is fully responsive. When you resize the PWA window, the title bar reacts as if it were composed of regular HTML content, which, in fact, it is.
Determining which parts of the title bar are draggable
While the screenshot above suggests that you are done, you are not done quite yet. The PWA window is
no longer draggable (apart from a very small area), since the window controls buttons are not drag
areas, and the rest of the title bar consists of the search widget. Fix this using
the app-region
CSS property with a value of drag
. In the concrete case, it is fine to make
everything besides the input
element draggable.
/* The entire search `div` is draggable… */
.search {
-webkit-app-region: drag;
app-region: drag;
}
/* …except for the `input`. */
input {
-webkit-app-region: no-drag;
app-region: no-drag;
}
With this CSS in place, the user can drag the app window as usual by dragging the div
, the img
,
or the label
. Only the input
element is interactive so the search query can be entered.
Feature detection
Support for Window Controls Overlay can be detected by testing for the existence of
windowControlsOverlay
:
if ('windowControlsOverlay' in navigator) {
// Window Controls Overlay is supported.
}
Querying the window controls region with windowControlsOverlay
The code so far has one problem: on some platforms the window controls are on the right, on
others they are on the left. To make matters worse, the "three dots" Chrome menu will change
position, too, based on the platform. This means that the linear gradient background image needs to
be dynamically adapted to run from #131313
→maroon
or maroon
→#131313
→maroon
, so that it
blends in with the title bar's maroon
background color which is determined by
<meta name="theme-color" content="maroon">
. This can be achieved by querying the
getTitlebarAreaRect()
API on the navigator.windowControlsOverlay
property.
if ('windowControlsOverlay' in navigator) {
const { x } = navigator.windowControlsOverlay.getTitlebarAreaRect();
// Window controls are on the right (like on Windows).
// Chrome menu is left of the window controls.
// [ windowControlsOverlay___________________ […] [_] [■] [X] ]
if (x === 0) {
div.classList.add('search-controls-right');
}
// Window controls are on the left (like on macOS).
// Chrome menu is right of the window controls overlay.
// [ [X] [_] [■] ___________________windowControlsOverlay [⋮] ]
else {
div.classList.add('search-controls-left');
}
} else {
// When running in a non-supporting browser tab.
div.classList.add('search-controls-right');
}
Rather than having the background image in the .search
class CSS rules directly (as before), the
modified code now uses two classes that the code above sets dynamically.
/* For macOS: */
.search-controls-left {
background-image: linear-gradient(90deg, #36c, 45%, #131313, 90%, #36c);
}
/* For Windows: */
.search-controls-right {
background-image: linear-gradient(90deg, #36c, #131313, 33%, #36c);
}
Determining if the window controls overlay is visible
The window controls overlay will not be visible in the title bar area in all circumstances. While it
will naturally not be there on browsers that do not support the Window Controls Overlay feature, it
will also not be there when the PWA in question runs in a tab. To detect this situation, you can
query the visible
property of the windowControlsOverlay
:
if (navigator.windowControlsOverlay.visible) {
// The window controls overlay is visible in the title bar area.
}
Alternatively, you can also use the display-mode
media query in JavaScript and/or CSS:
// Create the query list.
const mediaQueryList = window.matchMedia('(display-mode: window-controls-overlay)');
// Define a callback function for the event listener.
function handleDisplayModeChange(mql) {
// React on display mode changes.
}
// Run the display mode change handler once.
handleDisplayChange(mediaQueryList);
// Add the callback function as a listener to the query list.
mediaQueryList.addEventListener('change', handleDisplayModeChange);
@media (display-mode: window-controls-overlay) {
/* React on display mode changes. */
}
Being notified of geometry changes
Querying the window controls overlay area with getTitlebarAreaRect()
can suffice for one-off
things like setting the correct background image based on where the window controls are, but in
other cases, more fine-grained control is necessary. For example, a possible use case could be to
adapt the window controls overlay based on the available space and to add a joke right in the window
control overlay when there is enough space.
You can be notified of geometry changes by subscribing to
navigator.windowControlsOverlay.ongeometrychange
or by setting up an event listener for the
geometrychange
event. This event will only fire when the window controls overlay is visible, that
is, when navigator.windowControlsOverlay.visible
is true
.
const debounce = (func, wait) => {
let timeout;
return function executedFunction(...args) {
const later = () => {
clearTimeout(timeout);
func(...args);
};
clearTimeout(timeout);
timeout = setTimeout(later, wait);
};
};
if ('windowControlsOverlay' in navigator) {
navigator.windowControlsOverlay.ongeometrychange = debounce((e) => {
span.hidden = e.titlebarAreaRect.width < 800;
}, 250);
}
Rather than assigning a function to ongeometrychange
, you can also add an event listener to
windowControlsOverlay
as below. You can read about the difference between the two on
MDN.
navigator.windowControlsOverlay.addEventListener(
'geometrychange',
debounce((e) => {
span.hidden = e.titlebarAreaRect.width < 800;
}, 250),
);
Compatibility when running in a tab and on non-supporting browsers
There are two possible cases to consider:
- The case where an app is running in a browser that supports Window Controls Overlay, but where the app is used in a browser tab.
- The case where an app is running in a browser that does not support Window Controls Overlay.
In both cases, by default the HTML built for the window controls
overlay will display inline like regular HTML content and the env()
variables' fallback values
will kick in for the positioning. On supporting browsers, you can also decide to not display the
HTML designated for the window controls overlay by checking the overlay's visible
property, and if
it reports false
, then hiding that HTML content.
As a reminder, non-supporting browsers will either not consider the
"display_override"
web app manifest property at all, or not recognize the
"window-controls-overlay"
and thus use the next possible value according to the fallback chain,
for example, "standalone"
.
UI considerations
While it may be tempting, creating a classic dropdown menu in the Window Controls Overlay area is not recommended. Doing so would violate the design guidelines on macOS, a platform on which users expect menu bars (both system-provided ones and custom ones) at the top of the screen.
If your app provides a fullscreen experience, carefully consider whether it makes sense
for your Window Controls Overlay to be part of the fullscreen view. Potentially you may
want to rearrange your layout when the
onfullscreenchange
event fires.
Demo
I have created a demo that you can play with in different supporting and non-supporting browsers and in the installed and non-installed state. For the actual Window Controls Overlay experience, you need to install the app. You can see two screenshots of what to expect below. The source code for the app is available on Glitch.
The search feature in the window controls overlay is fully functional:
Security considerations
The Chromium team designed and implemented the Window Controls Overlay API using the core principles defined in Controlling Access to Powerful Web Platform Features, including user control, transparency, and ergonomics.
Spoofing
Giving sites partial control of the title bar leaves room for developers to spoof content in what was previously a trusted, browser-controlled region. Currently, in Chromium browsers, standalone mode includes a title bar which on initial launch displays the title of the webpage on the left, and the origin of the page on the right (followed by the "settings and more" button and the window controls). After a few seconds, the origin text disappears. If the browser is set to a right-to-left (RTL) language, this layout is flipped such that the origin text is on the left. This opens the window controls overlay to spoof the origin if there is insufficient padding between the origin and the right edge of the overlay. For example, the origin "evil.ltd" could be appended with a trusted site "google.com", leading users to believe that the source is trustworthy. The plan is to keep this origin text so that users know what the origin of the app is and can ensure that it matches their expectations. For RTL configured browsers, there must be enough padding to the right of the origin text to prevent a malicious website from appending the unsafe origin with a trusted origin.
Fingerprinting
Enabling the window controls overlay and draggable regions do not pose
considerable privacy concerns other than feature detection. However, due to
differing sizes and positions of the window control buttons across operating
systems, the
navigator.
method returns a DOMRect
whose position and dimensions reveal information about the operating system upon
which the browser is running. Currently, developers can already discover the OS
from the user agent string, but due to fingerprinting concerns, there is
discussion about freezing the UA string and unifying OS versions. There is an
ongoing effort within the browser community to understand how frequently the
size of the window controls overlay changes across platforms, as the current
assumption is that these are fairly stable across OS versions and thus would not
be useful for observing minor OS versions. Although this is a potential
fingerprinting issue, it only applies to installed PWAs that use the custom
title bar feature and does not apply to general browser usage. Additionally, the
navigator.
API will not be available to
iframes embedded inside of a PWA.
Navigation
Navigating to a different origin within a PWA will cause it to fall back to the normal standalone title bar, even if it meets the above criteria and is launched with the window controls overlay. This is to accommodate the black bar that appears on navigation to a different origin. After navigating back to the original origin, the window controls overlay will be used again.
Feedback
The Chromium team wants to hear about your experiences with the Window Controls Overlay API.
Tell us about the API design
Is there something about the API that doesn't work like you expected? Or are there missing methods or properties that you need to implement your idea? Have a question or comment on the security model? File a spec issue on the corresponding GitHub repo, or add your thoughts to an existing issue.
Report a problem with the implementation
Did you find a bug with Chromium's implementation? Or is the implementation different from the spec?
File a bug at new.crbug.com. Be sure to include as much detail as you can,
simple instructions for reproducing, and enter UI>Browser>WebAppInstalls
in the Components
box. Glitch works great for sharing quick and easy repros.
Show support for the API
Are you planning to use the Window Controls Overlay API? Your public support helps the Chromium team to prioritize features and shows other browser vendors how critical it is to support them.
Send a Tweet to @ChromiumDev with the
#WindowControlsOverlay
hashtag and let us know where and how you're using it.
Helpful links
- Explainer
- Spec draft
- Chromium bug
- Chrome Platform Status entry
- TAG review
- Microsoft Edge's related docs
Acknowledgements
Window Controls Overlay was implemented and specified by Amanda Baker from the Microsoft Edge team. This article was reviewed by Joe Medley and Kenneth Rohde Christiansen. Hero image by Sigmund on Unsplash.