Modern Web Weekly #80
Another iOS version, another PWA issue…
In iOS 26, Apple stopped supporting the theme-color meta tag and started rendering PWAs fullscreen by default, which means that content would now render underneath the status bar, regardless of whether the viewport meta tag contained viewport-fit=cover.
In iOS27, the behavior has changed again, and installed PWAs now render a blur at the top of the screen:
For some reason, this is only the case when the PWA is installed. When opened in Safari, there is a small blur that’s roughly the height of the status bar:
In the installed PWA, the blur expands much further down and covers content that is near the top of the page. Understandably, developers are not happy with this and have been looking for ways to get rid of it.
I tested this on iOS27 and came to the following conclusions.
First, what doesn’t work:
Setting a color for the status bar with
<meta name=”theme-color” content=”#ff0000”>(red in this case). This meta tag is no longer supported since iOS26 and has no effectSetting
<meta name=”apple-mobile-web-app-status-bar-style” content=”default|black|black-translucent”>. This meta tag is deprecated and has no effectSetting a background-color on <body>. While the status bar will get the same color as the background color of <body>, the blur will be rendered below it, and the status bar will render a gradient when the page is scrolled up, as shown in the screenshots below:
What does work is positioning an element with position: fixed and a background color near the top of the screen. The status bar will then take on the background color of that element, and it will stay in place with a solid background color when the page is scrolled:
The element with position: fixed must:
be at least 6px high
have a width of at least 80% on iOS
be positioned within 4px of the top of the screen
This is currently the only thing that renders a status bar with a solid background color without a blur on iOS. I haven’t found a way to render a transparent status bar without a blur, and I don’t think this is possible right now.
But hey, since this is Apple, who knows what the behavior will be in the next versions…
Add content to the title bar with window-controls-overlay
In desktop PWAs, you can add content inside the title bar when the PWA is installed. This works for Chromium-based browsers on both macOS and Windows by setting the “display_override” key of manifest.json to “window-controls-overlay”":
{
"display_override": ["window-controls-overlay"]
}When this is set, a chevron will appear in the title bar in Chrome, which enables you to toggle between the standard title bar and the window controls overlay mode:
When toggled, it looks like this:
This is the area where you can place HTML content using the following environment variables:
toolbar-area-xtoolbar-area-ytoolbar-area-widthtoolbar-area-height
By using these variables in combination with position: fixed, you can add content that stays in place when the page is scrolled:
.window-controls {
position: fixed;
left: env(titlebar-area-x);
top: env(titlebar-area-y);
width: env(titlebar-area-width);
height: env(titlebar-area-height);
window-drag: move;
}By adding window-drag: move, the window controls area becomes a drag area for the application window, so when you drag it, the window is moved.
The Window Controls Overlay API also exposes the WindowControlsOverlay interface on navigator. It has the property visible, which is a boolean indicating if the window controls overlay is visible or not, and the method getTitlebarAreaRect() which returns the size and position of the title bar as a DOMRect object.
It also fires the “geometrychange” event whenever the position, size, or visibility of a PWA's title bar area changes:
navigator.windowControlsOverlay.addEventListener("geometrychange", e => {
const { x, y, width, height } = e.titlebarAreaRect;
});What PWA Can Do Today now displays a search box in the title bar to find and navigate to demos.
In Edge, there is no toggle, and the window controls overlay is shown permanently.
Check the demo.
Opening files with a PWA
Just like native applications, PWAs can open files and be configured as the default application to open a file with.
This feature is desktop only and is supported on macOS, Windows, and ChromeOS.
To register your PWA as a file handler, you first need to specify which files it can handle:
"file_handlers": [
{
"action": "/file-handling",
"accept": {
"image/pgn": [".png"],
"image/jpeg": [".jpg", ".jpeg"],
"image/webp": [".webp"]
}
}
],
"launch_handler": {
"client_mode": "focus-existing"
},The file_handlers member holds an array of objects with the following properties:
action: a URL within the scope of the PWA that will be navigated to when a file is opened with the PWAaccept: an array of MIME types and extensions for the files the PWA can handle
The launch_handler object decides how the PWA will be launched and has a single key client_mode that can have the following values:
auto: the user agent decides how the PWA will be launchedfocus-existing: if the PWA is already open, it will be focused, but the launch target URL will not be navigated tonavigate-existing: if the PWA is already open, it will be focused, and the launch target URL will be navigated tonavigate-new: the launch target URL will be navigated to in a new instance of the PWA
The file(s) that a user selects will be available in window.launchQueue and by setting a consumer for the file(s) through the launchQueue.setConsumer(), the files can be handled.
The consumer is set by passing a callback function to setConsumer that receives a launchParams object whose files property contains the selected files as an array of fileHandle objects:
launchQueue.setConsumer(async (launchParams) => {
if(launchParams.files.length) {
for(const fileHandle of launchParams.files) {
const file = await fileHandle.getFile();
const url = URL.createObjectURL(file);
const img = document.createElement('img');
img.src = url;
// do something with the <img>
}
}
});And that’s it! Your PWA can now open files on desktop.
You can either do so by right-clicking the file and choosing “Open with…” or set it as the default app that a specific file type will always be opened with. This works on both Windows and macOS with PWAs installed through a Chromium-based browser.
Check the demo.
Ship A PWA Users Can Trust
When you deploy a new version of your PWA, you want to have the confidence that it doesn't quietly break offline support, serve stale files, or leave the service worker stuck somewhere in its lifecycle.
The PWA Runtime Audit finds runtime failures under real-world conditions, before your users do.
It checks if your PWA:
is configured correctly
is installable
works offline after an update
works after a cold start while offline
goes correctly through the service worker lifestyle
serves the correct cached content while offline
retries requests made offline when back online
receives push notifications
Integrate it as part of your CI/CD pipeline so in case something breaks, you get a clear report showing what broke, why it broke, and what to fix first.
Ship a PWA your users can trust.
