CSS display-mode Media Feature

What You’ll Learn

The display-mode media feature detects how your page is shown — in a browser tab, as an installed PWA, fullscreen, or with minimal UI. Adapt styles to match the launch context.

Introduction

The @media (display-mode) feature applies CSS based on how the user opened your site. A page in a normal browser tab behaves differently from the same page launched as an installed Progressive Web App (PWA) from a home screen or desktop shortcut.

With display-mode, you can hide browser-only UI (like install banners), add app-style navigation, adjust safe-area padding, and create immersive fullscreen experiences for games and media.

Definition and Usage

Write @media (display-mode: standalone), @media (display-mode: browser), or other values inside your stylesheet. When the page runs in that mode, the nested rules apply.

📝 Syntax

Use a display mode keyword inside an @media rule:

@media (display-mode: standalone) {
  /* Installed PWA without browser toolbar */
}

@media (display-mode: fullscreen) {
  /* Full screen, no browser UI */
}

@media (display-mode: browser) {
  /* Standard browser tab */
}

Accepted Values

• browser — Standard browser window with full address bar and controls (default when visiting a URL).
• standalone — Installed PWA running in its own window without browser UI.
• minimal-ui — Minimal browser chrome; some navigation controls remain visible.
• fullscreen — Entire screen; no browser UI at all.
• window-controls-overlay — Desktop PWA with the Window Controls Overlay API active.

Display Modes at a Glance

Basic Example

@media (display-mode: standalone) {
  body {
    background-color: #dcfce7;
  }
}

@media (display-mode: fullscreen) {
  body {
    background-color: #dbeafe;
  }
}

@media (display-mode: browser) {
  body {
    background-color: #fff;
  }
}

Media Feature vs CSS Property

Default Value

There is no CSS default. When visiting a URL in a tab, the mode is typically browser.

Syntax Rules

• One keyword per query: (display-mode: standalone).
• Combine with other features: @media (display-mode: standalone) and (min-width: 48rem).
• PWA manifest display field sets the preferred mode when installed.
• Only one display mode is active at a time per viewport.
• Test by installing the PWA and opening from home screen vs browser tab.

Related Topics

• display property — element layout (block, flex, grid)
• any-hover — detect hover capability
• aspect-ratio — viewport shape queries

When to Use display-mode

Reach for display-mode when launch context changes the UI:

• PWA install prompts — Hide “Install app” banners in standalone mode.
• App-style navigation — Show bottom nav or header chrome when browser toolbar is absent.
• Safe-area padding — Adjust for notches when running as a fullscreen or standalone app.
• Immersive media — Expand video or game UI in fullscreen.
• Browser-only promos — Show marketing chrome only in browser mode.

Examples Gallery

Practice display-mode with PWA backgrounds, install banners, app navigation, and fullscreen layouts.

@media (display-mode: standalone) {
  body {
    background-color: #dcfce7;
  }
}

@media (display-mode: fullscreen) {
  body {
    background-color: #dbeafe;
  }
}

@media (display-mode: browser) {
  body {
    background-color: #fff;
  }
}

.install-banner {
  display: flex;
  padding: 0.75rem 1rem;
  background: #eff6ff;
  border: 1px solid #93c5fd;
  border-radius: 0.5rem;
  font-size: 0.875rem;
}

@media (display-mode: standalone) {
  .install-banner {
    display: none;
  }
}

@media (display-mode: fullscreen) {
  .install-banner {
    display: none;
  }
}

.app-nav {
  display: none;
}

@media (display-mode: standalone) {
  .app-nav {
    display: flex;
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    justify-content: space-around;
    padding: 0.65rem;
    background: #fff;
    border-top: 1px solid #e2e8f0;
  }
  body {
    padding-bottom: 3.5rem;
  }
}

.site-header {
  padding: 1rem 1.5rem;
  background: #1e293b;
  color: #fff;
}

@media (display-mode: fullscreen) {
  .site-header {
    display: none;
  }
  .player {
    min-height: 100vh;
    background: #000;
  }
}

💬 Usage Tips

• Match manifest display — Set "display": "standalone" in your web app manifest for consistent PWA behavior.
• Hide redundant UI — Remove install prompts and browser promos in standalone/fullscreen.
• Safe-area insets — Combine with env(safe-area-inset-*) for notched phones in standalone.
• Test both contexts — Open the same URL in a tab and from the home screen icon.
• Progressive defaults — Browser mode should work fully without PWA-specific styles.

⚠️ Common Pitfalls

• Confusing with display property — Media display-mode ≠ CSS display: flex.
• Assuming standalone on desktop — Users may always use browser mode unless they install the PWA.
• Hiding essential nav — Ensure browser-mode users can still navigate without the PWA bottom bar.
• Only styling standalone — Consider fullscreen and minimal-ui too if your manifest supports them.
• Skipping browser testing — Most first visits happen in browser mode.

♿ Accessibility

• Keyboard navigation — App-style nav must remain keyboard accessible in standalone mode.
• Exit fullscreen — Provide a visible control to leave fullscreen; don’t trap users.
• Focus management — When hiding headers, ensure focus order still makes sense.
• Contrast in all modes — PWA chrome changes must still meet WCAG contrast requirements.
• Don’t rely on mode alone — Core content must work in browser mode without installation.

💡 Best Practices