Web apps on iOS work — millions of people have them on their home screens — but Apple's support is quieter than Google's and the differences trip up everyone the first time. This guide is the current state as of iOS 17/18, written for people who need to get their own users through it.
How installation works
There is no install prompt. Safari never volunteers. The user must:
- Open your site in Safari (or, since iOS 16.4, in another browser that supports it — Chrome for iOS does, via its own menu).
- Tap the Share button (the square with an arrow, bottom centre on iPhone).
- Scroll the sheet and tap Add to Home Screen.
- Confirm the name; tap Add.
Four steps, one of which requires scrolling a sheet full of unrelated options. Your install page exists to walk them through it — see below.
What Safari reads
| Source | Used for |
|---|---|
<link rel="apple-touch-icon"> | The home-screen icon. Required — Safari ignores manifest icons for this. 180×180 PNG, no transparency. Without it you get a screenshot of the page. |
Manifest name / short_name | Default name in the Add dialog |
Manifest display: standalone | Opens without Safari UI. fullscreen is treated as standalone. |
Manifest start_url, scope | Where it opens; what stays in-app |
Manifest theme_color, background_color | Status bar area and launch background (partial support; varies by version) |
<meta name="apple-mobile-web-app-status-bar-style"> | default, black or black-translucent for the status bar |
Manifest orientation, screenshots, shortcuts | Ignored |
What an installed web app can do on iOS
- Run standalone with its own icon and app-switcher card.
- Work offline through the service worker — full support.
- Receive push notifications — since iOS 16.4 (March 2023), only for apps added to the home screen, and only after the user grants permission in response to a tap. Badging the icon is supported too.
- Keep its data. Safari's 7-day cap on script-writable storage for websites you haven't used does not apply to home-screen web apps, which get their own storage that persists like an app's.
- Use the camera, microphone, geolocation, Apple Pay on the web, passkeys, WebGL.
What it cannot do
- Prompt to install, or detect reliably whether it is installed (you can check
navigator.standaloneonce running). - Use Web Bluetooth, Web NFC, Web USB, background sync, or background geolocation.
- Lock orientation from the manifest, or go fullscreen past the status bar.
- Appear in the App Store. Distribution is your website, full stop.
- Share cookies and login state with Safari. An installed web app is a separate browsing context; users sign in once inside the app.
The install page copy that works
Detect iOS (/iPhone|iPad|iPod/.test(navigator.userAgent) is still the practical way) and show iOS-specific steps, ideally with a screenshot of the share sheet. Text that has tested well:
Add to your Home Screen
1. Tap the Share button at the bottom of Safari.
2. Scroll down and tap Add to Home Screen.
3. Tap Add.
Takes ten seconds. No App Store, no account.
Two details matter: say "Safari" explicitly if you detect an in-app browser (Instagram's and Facebook's in-app browsers cannot add to home screen — offer "Open in Safari"); and don't hide the instructions behind a button, because the people who need them are the ones who wouldn't click it. The install page guide has the full pattern.
Testing checklist
- Icon appears correctly after Add to Home Screen (not a screenshot).
- Opens standalone — no Safari toolbar.
- Internal links stay in the app; external links open Safari.
- Aeroplane mode: previously visited pages load; others show your offline page.
- If you use push: the permission prompt appears only after a tap, and a test notification arrives with the app closed.
- Rotate: the layout copes with landscape, since orientation can't be locked.