Web App Manifest Properties Supported by Safari
This article provides a breakdown of the specific Web App Manifest JSON properties that Apple's Safari browser reads and applies when configuring a standalone Progressive Web Application (PWA). By understanding how Safari utilizes properties for display modes, icons, colors, and navigation scopes, developers can ensure their web applications behave like native apps across iOS, iPadOS, and macOS.
name and
short_name
Safari reads these properties to determine the text label displayed
beneath the application icon on the iOS Home Screen, iPadOS Home Screen,
or macOS Dock. Safari prioritizes short_name if it is
present so the text does not truncate. If short_name is
omitted, it falls back to name.
display
This property dictates how much of the standard browser user
interface is shown to the user. To configure a standalone web
application, Safari looks for the standalone value, which
hides the Safari address bar and bottom navigation toolbars. Safari also
reads fullscreen, minimal-ui, and
browser. However, on iOS and iPadOS,
fullscreen falls back to standalone (keeping
the system status bar visible), and minimal-ui falls back
to standard browser behavior.
start_url
Safari reads the start_url property to determine which
specific URL to load when the user launches the application from their
Home Screen or Dock. If this property is missing, Safari defaults to the
URL of the page the user was viewing when they added the app to their
device.
scope
The scope property defines the navigation boundary of
the web application. Safari reads this to know which URLs belong to the
app. If a user clicks a link that leads to a URL within the defined
scope, the navigation stays inside the standalone window.
If the user clicks a link outside the scope, Safari opens
that link in an overlay browser view (SFSafariViewController) on
iOS/iPadOS or in a standard Safari tab on macOS.
icons
Modern versions of Safari (iOS 15.4+ and macOS Sonoma+) read the
icons array to set the application icon. Safari looks for
the src, sizes, and type
sub-properties to pick the highest-resolution image available. Note that
if an HTML document includes the legacy
<link rel="apple-touch-icon"> tag, Safari will
prioritize the HTML tag over the manifest's icons
property.
theme_color
Safari uses the theme_color property to style the native
window frame surrounding the web content. In a standalone app on iOS and
iPadOS, this color is applied to the background of the top system status
bar. On macOS, Safari applies this color to the standalone window's
title bar.
background_color
Safari reads the background_color property to render a
solid background color immediately when the user launches the standalone
app. This color remains visible in the application window until the web
app's own CSS stylesheets have loaded and rendered.
id
Safari reads the id property to uniquely identify the
standalone web app. This allows Safari and the underlying operating
system to differentiate between multiple standalone web applications
that might be hosted on the exact same origin/domain.
orientation
Safari reads the orientation property (such as
portrait or landscape) to lock the display
orientation of the standalone application. This is primarily enforced on
iOS, as iPadOS multitasking features and macOS window management allow
users to resize windows freely, overriding this manifest property.
shortcuts
On iOS and iPadOS, Safari reads the shortcuts array to
generate quick actions. When a user long-presses the standalone web
app's icon on the Home Screen, the operating system displays a context
menu containing the links and titles defined in this property.