Definition

display-mode media query

Short definition

display-mode is a CSS media feature, usable both in stylesheets (@media (display-mode: standalone) { ... }) and in JavaScript via window.matchMedia("(display-mode: standalone)").matches, that reports which of browser, minimal-ui, standalone or fullscreen is currently applied to the page — regardless of what the manifest requested, since the OS can downgrade the requested mode.

Reviewed August 11, 2026

A common CSS use is adding safe-area padding or hiding a redundant in-page "back" button only when running standalone: @media (display-mode: standalone) { .app-header { padding-top: env(safe-area-inset-top); } }.

Because display-mode reflects the mode actually in effect rather than the value requested in the manifest, it is the correct tool for any conditional logic about the *current* session, whereas the manifest's display field is only ever a request evaluated at install/launch time.

The media feature can be watched for changes with matchMedia(...).addEventListener("change", handler), useful on desktop where a user can, in some browsers, toggle window controls overlay related modes without a full reload.

It is specified as part of the Media Queries used by the Web App Manifest spec and documented at https://developer.mozilla.org/en-US/docs/Web/CSS/@media/display-mode.

Related terms

display (manifest field)

display is the manifest field that chooses the browser chrome level for the installed app. Accepted values are fullscreen, standalone, minimal-ui and browser. "display": "standalone" is the most common choice because it hides the address bar and tab strip while keeping the OS status bar visible.

Standalone mode detection

Standalone mode detection means checking, at runtime, whether the current page is running as an installed app rather than a regular tab. On Chromium and most browsers this is window.matchMedia("(display-mode: standalone)").matches; on iOS Safari the historical equivalent is the non-standard navigator.standalone boolean, since iOS predates the display-mode media feature's adoption there.

display_override (manifest field)

display_override is a manifest array, for example "display_override": ["window-controls-overlay", "standalone"], that lets a site opt into newer or experimental display modes such as window-controls-overlay on desktop, while still declaring a safe fallback. The browser walks the list in order and uses the first mode it understands.

beforeinstallprompt userChoice

userChoice is a property on the deferred beforeinstallprompt event, resolving to an object like { outcome: "accepted" | "dismissed", platform: "web" }, available after calling deferredEvent.prompt(). It is the only reliable, synchronous-feeling signal for whether a user actually accepted or dismissed your custom install prompt in that specific interaction.

Service worker

A service worker is a JavaScript file the browser runs in the background, separate from the page. It intercepts network requests, caches responses so the site works offline, and receives web-push events so the site can notify the user when it is closed.

Web App Manifest

A Web App Manifest is a JSON file (usually manifest.webmanifest) that declares your app's name, icons, start URL, theme colour and display mode. The browser reads it to render the install prompt and the home-screen icon.