Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Web App Manifest

Display Modes, Colors and Orientation

Control how your PWA looks when launched: display modes (standalone, fullscreen, minimal-ui), display_override, theme and background colors, and orientation.

When a user opens your installed PWA, the browser decides what chrome (address bar, buttons, tabs) to draw around it. You control that decision with a few manifest members. Together they decide whether the app feels like a website in a window or a real application: its title bar color, splash screen, whether the URL bar is visible, and whether the screen can rotate.

display

display sets the preferred display mode.

Value What the user sees
fullscreen No browser or OS chrome at all. Good for games and immersive tools.
standalone Looks like a native app: own window, no address bar, a small title bar. The usual choice.
minimal-ui Standalone plus a minimal set of controls such as back and reload.
browser A normal browser tab. The default if you set nothing.

Chromium requires standalone, fullscreen or minimal-ui for the install criteria. Browsers fall back along this chain if a mode is not available: fullscreen, standalone, minimal-ui, browser.

JSON
{ "display": "standalone" }

display_override

display only lets you name one value, and unknown values are ignored. display_override is an ordered list of modes the browser tries first, using the first one it supports. It also allows newer modes:

  • window-controls-overlay: on desktop, your content extends into the title bar area so you can draw your own header next to the window buttons.
  • tabbed: an app window with tabs (experimental).
  • borderless: a very frameless window (experimental, with permission).
JSON
{
  "display": "standalone",
  "display_override": ["window-controls-overlay", "standalone"]
}

Keep display as the fallback for browsers that do not understand display_override.

Detecting the mode in CSS and JavaScript

Your page can adapt to how it was launched with the display-mode media feature. Hide the "Install" button when already installed, add padding for the title bar, or show a back button in standalone mode where there is no browser back button.

CSS
@media (display-mode: standalone) {
  .install-hint { display: none; }
  header { padding-top: env(safe-area-inset-top); }
}

In JavaScript:

JavaScript
const isStandalone =
  window.matchMedia('(display-mode: standalone)').matches ||
  navigator.standalone === true;   // old iOS Safari

The following TryIt shows the idea. In this preview the page runs in a normal browser tab, so only browser matches. Run the same code in an installed PWA and standalone will match instead.

JS Which display mode am I in?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Colors: theme_color and background_color

Two colors shape how your app feels while loading and running.

  • theme_color tints the title bar or status bar of the app window (and the browser UI on mobile). Pick your brand's main color.
  • background_color is shown on the splash screen while the app starts, before your CSS loads. Use the same color as your page background so the transition is smooth.
JSON
{
  "theme_color": "#0b6e4f",
  "background_color": "#ffffff"
}

The manifest colors are only used for installed apps. For normal browser tabs, set the theme-color meta tag in HTML, which also supports dark mode variants:

HTML
<meta name="theme-color" content="#0b6e4f" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#0a2e22" media="(prefers-color-scheme: dark)">

Use a contrasting title bar: white text on a very light theme color is unreadable. Colors should meet accessibility contrast guidelines too. Try the following demo: it checks the contrast ratio between two colors using the WCAG formula.

JS Contrast check for theme colors

Press Run (or Ctrl + Enter) to see the console output here.

No output.

orientation

orientation locks or hints the screen rotation of the installed app.

Value Meaning
any Any rotation (default behavior)
natural The device's natural orientation
portrait, portrait-primary, portrait-secondary Upright
landscape, landscape-primary, landscape-secondary Sideways

Be careful: locking the orientation breaks usability for people who mount their device in a fixed position, such as on a wheelchair, and for foldables. Lock only when the experience truly requires it, such as a game or a camera tool. Reading apps should not.

JSON
{ "orientation": "portrait" }

Putting it together

A complete set of presentation members for a notes app:

JSON
{
  "display": "standalone",
  "display_override": ["window-controls-overlay", "standalone"],
  "theme_color": "#0b6e4f",
  "background_color": "#ffffff",
  "orientation": "any"
}

Splash screens

You do not draw a splash screen yourself. On Android and desktop Chromium, the browser builds it from name, a suitable icon (usually the 512 px) and background_color. On iOS the splash comes from apple-touch-startup-image links, one per device size, which most projects skip in favor of a plain background color.

A mode-aware layout stand-in

Real apps change their layout by mode. This stand-in picks UI decisions from a mode string, the same way your CSS and JavaScript would.

JS Stand-in: UI decisions per display mode

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which display value makes the app look like a native app, with its own window and no address bar?

    standalone is the usual PWA choice.
  2. 2. What does display_override do?

    The browser uses the first supported mode in display_override, otherwise display.
  3. 3. background_color is used for what?

    It fills the splash screen before the app's CSS has loaded.
  4. 4. Why should you avoid locking orientation for a reading app?

    Locking removes a basic accessibility choice for users.

Summary

  • display: standalone is the standard for an app-like window; display_override lets you try newer modes first.
  • Detect the active mode with the display-mode media query and adapt the UI.
  • theme_color tints the window chrome; background_color fills the splash screen.
  • Add theme-color meta tags for normal browser tabs, including dark mode.
  • Lock orientation only when truly necessary.

Next: The Install Prompt and Custom Install Buttons