PWAs hosted within a user agent (UA) frame are able to declare which browser display mode best meets the needs of the application via the manifest file’s display member. Currently, there are 4 supported values and their behaviors on Chromium browsers are described below:
fullscreen: All of the available display is used and no UA chrome is shown. This is implemented only for mobile devices running Android or iOS.
standalone: The web app looks like a standalone application. The title bar includes the title of the application, a web app menu button, and caption control buttons (minimize, maximize/restore, close).
minimal-ui: Similar to standalone, except it also contains a back and refresh button.
browser: Currently, the same as minimal-ui
Problem
Developers want to create an immersive, native-like title bar for their desktop applications, but the display modes listed above do not support this. Instead, developers must shift content down below the reserved title bar area, which can create a cramped application space especially on portable devices with smaller screens.
Proposal
The solution proposed in this explainer is broken down into multiple parts:
A new display modifier option for the web app manifest - "caption-controls-overlay"
New APIs for developers to query the bounding rects and other states of the UA provided caption controls overlay which will overlay into the web content area through a new object on the window.navigator property called controlsOverlay
New CSS environment variables to define the left and right insets from the edges of the window: unsafe-area-top-inset-left and unsafe-area-top-inset-right
A standards-based way for developers to define system drag regions on their content
Apparently I forgot to explain the most important concept, so thanks for calling that out!
The caption controls overlay is a notch-like overlay that would live in the upper-left or upper-right corner of the window and contains the caption control buttons (minimize, maximize/restore, close), a small draggable region, and any other controls required for privacy and security (e.g. the three-dot menu button in Chromium provides site security information and more).
Sorry, but I must be missing something still. What does you mean by caption here? To me, a caption is a bit of text that overlays a video with a transcription of the audio. But that doesn’t make sense to me in this context, so I assume you mean something else.
Is this a widely used term outside of Microsoft? I’ve never heard that before, and the first page of a Google search for “caption controls” in quotes only returns results about captioning and subtitles.
If this is a Windows-specific term or a Microsoft-specific term, perhaps there’s a more general term that would better fit a web API that is not OS-specific.
In the case of ChromeOS, I would guess that the top of the window frame would still be called a “title bar” even if it doesn’t have a title in it, just because that is visually similar to a title bar. I’d be interested to hear what others would refer to it as.
That said, I do like windows-controls-overlay because it describes the main feature of the overlay: the window controls. The only concern that I have is that it could lead people to believe that it only contains the window controls, when in reality, it also contains a few other buttons/items.
We’ve updated the explainer title and content per feedback here and elsewhere:
Window Controls Overlay for Installed Desktop Web Apps
Background
PWAs hosted within a user agent (UA) frame are able to declare which browser display mode best meets the needs of the application via the manifest file’s display member . Currently, there are 4 supported values and their behaviors on Chromium browsers are described below:
fullscreen : All of the available display is used and no UA chrome is shown. This is implemented only for mobile devices running Android or iOS.
standalone : The web app looks like a standalone application. The title bar includes the title of the application, a web app menu button, and window control buttons (minimize, maximize/restore, close).
minimal-ui : Similar to standalone , except it also contains a back and refresh button.
browser : Currently, the same as minimal-ui
Problem
Developers want to create an immersive, native-like title bar for their desktop applications, but the display modes listed above do not support this. Instead, developers must shift content down below the reserved title bar area, which can create a cramped application space especially on portable devices with smaller screens.
Proposal
Add the option extend the app’s client area to cover the entire window–including the title bar area–and overlay the window control buttons (close, maximize/restore, minimize) on top of the client area. A developer then use this feature to create an installed desktop app with the appearance of a native title bar.
Hello WICG chairs. This API now has interest from Google (issue link below) and Microsoft. I would like to request to move the explainer to a WICG repo for incubation. Thanks!
Additionally, we have setup https://github.com/WICG/window-controls-overlay to directly incubate the feature proposed in the subject of this thread. Note that display-override is a building block for the window-controls-overlay feature, however, the scenarios and uses cases are sufficiently different to merit each to incubate in separate repos. Thanks!