Safari: Legacy Meta Tags vs. Modern Web App Manifests

This article provides an overview of how the Safari web browser handles the interaction between legacy apple-mobile-web-app-capable meta tags and modern Web App Manifest settings. It covers the historical context of both methods, the exact precedence rules Safari uses when both are present in a web application, how conflicts between the two are resolved, and the best practices developers should follow for Progressive Web Apps (PWAs) on iOS and iPadOS.

The Two Approaches Defined

Before the W3C standardized the Web App Manifest, Apple introduced proprietary HTML meta tags to allow websites to look and behave like native apps when added to the iOS Home Screen.

The Legacy Meta Tag:

<meta name="apple-mobile-web-app-capable" content="yes">

When set to yes, this tag instructs Safari to open the web application in "standalone" mode, hiding the standard Safari user interface (such as the URL bar and navigation buttons).

The Web App Manifest: The modern approach uses a JSON file (typically manifest.json or manifest.webmanifest) linked in the HTML head. It controls the display mode using the display property:

{
  "name": "My Web App",
  "display": "standalone"
}

How Safari Evaluates Both Settings

Since iOS 11.3, Safari has supported the Web App Manifest standard. However, because millions of websites still use the legacy Apple meta tags, Safari follows specific logic to determine how to display a web app when both the meta tag and the manifest are present.

1. Alignment (No Conflict)

If the Web App Manifest specifies "display": "standalone" and the HTML includes <meta name="apple-mobile-web-app-capable" content="yes">, there is no conflict. Safari will launch the Home Screen web app in standalone mode without browser UI.

2. The Meta Tag Override Scenario

A conflict arises if the Web App Manifest requests a standard browser experience, but the legacy meta tag requests a full-screen experience:

  • Manifest: "display": "browser"
  • Meta Tag: content="yes"

In this scenario, the legacy meta tag overrides the Web App Manifest. Safari assumes that by explicitly including the Apple-specific meta tag, the developer intends to force the standalone experience on iOS devices, ignoring the manifest's browser setting.

3. Unsupported Manifest Display Modes

The Web App Manifest specification includes four display modes: fullscreen, standalone, minimal-ui, and browser. Safari on iOS does not support all of them natively and maps them as follows when no meta tags are present:

  • fullscreen falls back to standalone.
  • standalone renders as standalone.
  • minimal-ui falls back to browser.
  • browser renders as browser.

If you set your manifest to minimal-ui, Safari will normally open the app in the standard browser view. However, if you also include <meta name="apple-mobile-web-app-capable" content="yes"> as a fallback in your HTML, the meta tag will intercept the minimal-ui fallback and force the app into standalone mode instead.

4. Manifest Loading Failures

Safari fetches the Web App Manifest asynchronously. If a user taps "Add to Home Screen" before the manifest file has finished downloading, or if the manifest is blocked by a network error, Safari immediately falls back to the HTML meta tags. If apple-mobile-web-app-capable is present, the app will still be saved as a standalone app. If the meta tag is omitted and the manifest hasn't loaded, the app will be saved as a standard webpage bookmark.

The apple-mobile-web-app-capable tag also dictates how other legacy tags interact with the manifest:

  • Status Bar Style: The <meta name="apple-mobile-web-app-status-bar-style"> tag only functions if standalone mode is triggered (either via the manifest or the capable meta tag). It works alongside the manifest's theme_color property to style the top of the iOS screen.
  • App Titles: If both the <meta name="apple-mobile-web-app-title"> tag and the manifest's short_name or name properties are present, modern versions of Safari prioritize the apple-mobile-web-app-title tag for the Home Screen icon label.

Current Best Practices

Apple has officially begun deprecating the apple-mobile-web-app-capable meta tag in favor of the Web App Manifest and the more generic <meta name="mobile-web-app-capable" content="yes"> tag. Modern WebKit consoles now issue warnings when the legacy Apple tag is used.

To ensure predictable behavior in Safari:

  1. Rely on the Manifest: Use the Web App Manifest as your single source of truth for display modes. All modern iOS devices support it.
  2. Remove the Legacy Tag: Remove apple-mobile-web-app-capable from your HTML unless you explicitly need to support iOS versions older than 11.3, or if you need a synchronous fallback for users adding the page to their Home Screen on very slow connections.
  3. Avoid Contradictions: Never leave apple-mobile-web-app-capable set to yes if you intend to use "display": "browser" or "display": "minimal-ui" in your manifest, as the meta tag will break your intended layout on iOS.