Platform in Installation
iOS Add to Home Screen
Published Updated
“Add to Home Screen” adds a website to the iOS or iPadOS Home Screen from the Share sheet. It requires a user gesture and is the only install route. Safari has offered it since iPhone OS 1, and third-party browsers gained it in iOS 16.4. No version fires beforeinstallprompt or exposes an install API (BCD api.BeforeInstallPromptEvent). The page supplies a manifest along with icons and a name. The user decides how the icon launches, with an explicit “Open as Web App” switch on iOS 26.
How it works
Section titled “How it works”Tap Share, then Add to Home Screen. Edit the name if needed, then tap Add. From iOS 16.4 a third-party browser can offer the same item when it holds the com.apple.developer.web-browser entitlement, places a WKWebView showing an HTTP or HTTPS document in the Share sheet’s activityItems, and the device is not a Shared iPad (WebKit, “Web Push for Web Apps on iOS and iPadOS”).
What the icon does when tapped changed between 16.4 and 26:
| iOS version | Opens as a web app (own App Switcher entry, no Safari UI) when | Otherwise |
|---|---|---|
| 16.4 to 18 | The manifest’s display is standalone or fullscreen, or the legacy apple-mobile-web-app-capable meta tag is yes; the browser that added it does not matter |
Saved as a Home Screen bookmark that opens in the default browser |
| 26 | By default for every added site; the user can turn off “Open as Web App” in the add sheet even for a site configured as a web app | Bookmark, only when the user turned the switch off |
According to WebKit, Safari 26 has no installability requirements. It requires no manifest or service worker and makes no HTTPS check beyond loading the page. The manifest controls the web app’s appearance. icons have been read since iOS 15.4, name and short_name seed the editable title, id (16.4+) is combined with the user’s chosen name so that two installs of the same site (“Shiny (work)” and “Shiny (personal)”) stay distinguishable and Focus filters can treat them separately. Multiple installs of one site are supported and intentional.
HTML markup controls the icon, name, launch image, and status bar.
- For the icon,
<link rel="apple-touch-icon" sizes="180x180" href="…">wins over manifesticonswhen both exist; Apple’s archived guide documents using the icon that matches the device’s recommended size, otherwise the smallest icon larger than that size, otherwise the largest available. With no icon at all, iOS 16.4 and later draw a monogram from the first letter of the site name on a colour taken from the site. - The name comes from
<meta name="apple-mobile-web-app-title" content="…">, falling back to<title>. The user can edit it before adding. - The launch image defaults to a screenshot of the last launch;
<link rel="apple-touch-startup-image" href="…">overrides it, which matters offline. <meta name="apple-mobile-web-app-status-bar-style" content="black">styles the status bar only in standalone mode; Apple’s archived guide states it “has no effect unless you first specify standalone mode”. On iOS 18.6.2 the OpenPWA device test measured what the default andblack-translucentstyles do in an installed app: with no status-bar meta the viewport starts 62 px below the top of the screen (812 of 874 CSS px on an iPhone 16 Pro) andviewport-fit=coverchanges only the bottom inset, whileblack-translucentwithviewport-fit=covergives a full-height viewport withenv(safe-area-inset-top)of 62 px. The solid strip above a default-style page took the page’stheme-colormeta, and the manifesttheme_coloronly when the page had no meta (study, notebook N25 to N29, N55, N64, N65).
Once on the Home Screen, the web app gets capabilities a Safari tab does not: Web Push (16.4+, after a user gesture; Declarative Web Push in 18.4 subscribes through window.pushManager without a service worker) and the Badging API (16.4+, drawn once notifications are allowed). WebKit’s 16.4 announcement also names Screen Wake Lock, Screen Orientation and User Activation as new APIs “of particular interest” to Home Screen web app developers, but they shipped in Safari 16.4 itself and are not limited to installed apps (WebKit, “WebKit Features in Safari 16.4”). Screen Wake Lock did not work in Home Screen web apps until iOS 18.4, which WebKit lists as a fix (WebKit, “WebKit Features in Safari 18.4”; BCD api.WakeLock records 16.4 to 18.3 as partial for that reason). WebKit has not required a service worker for the Home Screen entry in any iOS version (WebKit, Safari 26.0 post). Storage stays best-effort: Safari deletes script-written data for an origin with no interaction in seven days of browser use when cross-site tracking prevention is on, and navigator.storage.persist() is answered from interaction history without a prompt (MDN, storage quotas and eviction).
Observed behaviour
Section titled “Observed behaviour”A web page cannot observe installation itself. It can detect the display context after launch.
Without an install event, branch on the display context. Use the standard media feature with the legacy property as a fallback for older iOS:
const standalone = matchMedia('(display-mode: standalone)').matches || navigator.standalone === true; // Safari-only legacy property
if (standalone) { hideInstallHint(); // launched from the Home Screen} else if (/iPhone|iPad/.test(navigator.userAgent)) { showShareMenuInstructions(); // "Tap Share, then Add to Home Screen"}Showing the hint on a second or later visit reaches fewer users, but makes it more relevant to returning visitors. The branch prevents an unnecessary hint inside a launched web app. The user-agent test chooses the instruction text only; capability is read from display-mode.
See also
Section titled “See also”- WebKit features in Safari 26.0 (webkit.org)
- Web Push for Web Apps on iOS and iPadOS (webkit.org)
- Configuring Web Applications (developer.apple.com)
- PWAs on iOS and Safari
- iOS Safari push
- Badging API
idmanifest member- Installability criteria
- Testing Home Screen web apps on iOS 18.6.2
Specifications
| Specification | Status |
|---|---|
| None. | |