Your PWA does not work on iPhone

Short answer

Four iOS-specific behaviours explain almost every case. There is no automatic install prompt — the user must use Share then Add to Home Screen, and nothing on the page can trigger it. Every browser on iOS uses Safari's engine, so "try Chrome instead" changes nothing. The installed app gets its own storage, separate from Safari, so a session created in the browser does not exist inside the icon. And push notifications require iOS 16.4 or later and only work once the app is on the Home Screen.

There is no install prompt, and there never was

On Android, Chrome offers to install. On iOS, nothing does. The user must tap Share, scroll past the sharing options, and find Add to Home Screen. No manifest field, no JavaScript API and no amount of engineering changes this — beforeinstallprompt does not exist on iOS.

This is the single largest source of "my PWA is broken on iPhone" reports, and the app is usually fine. What is missing is a page telling people the gesture. If a meaningful share of your traffic is iPhone, that page is the fix, not a manifest change.

Mentioned here: ✏️ Excalidraw, 🖼️ Photopea, 🔐 CryptPad

Every iOS browser is Safari

Chrome, Firefox, Edge and Brave on iOS are all WebKit with a different interface. So "it works in Chrome on my phone" tells you nothing about the engine, and "try another browser" is not a workaround for a WebKit bug — there is no other engine to try.

The practical consequence: if a feature is missing on iPhone, check WebKit support rather than the browser name. And test in Safari itself, because the in-app browsers inside Instagram, Facebook or Gmail add their own restrictions on top — installation from inside one of those is not possible at all.

The installed app has its own storage

This one produces the strangest bug reports. A user logs in through Safari, adds the app to their Home Screen, opens it, and is logged out. Nothing is broken: the standalone app has a separate cookie and storage jar from the browser that created it.

So the first launch of an installed iOS PWA is always a cold one. Anything you cached during the Safari visit is not there, and any session is gone. Design the first run accordingly — and if you gate content behind a login, expect that first screen to be the login.

Notifications need iOS 16.4 and the Home Screen

Web push works on iOS from 16.4 onward, and only for a web app that has been added to the Home Screen. In a Safari tab, the permission prompt does not appear at all. Asking for permission on page load will therefore look silently broken to most iPhone users.

The workable order is: explain, let them install, then ask from inside the installed app. Requesting permission before installation wastes the one prompt you get.

What is usually not the problem

Offline still behaves normally on iOS — service workers work, caches work. If your app opens blank rather than not opening at all, the cause is more likely one of the four generic ones than anything Apple-specific. Of 386 installable apps we measured, 235 show nothing offline on every platform, not just this one.

Icons are also usually fine: iOS applies its own rounded mask to apple-touch-icon regardless of what the manifest declares, so the white-circle problem is Android's, not Apple's.

Frequently asked

Can I show my own install button on iOS?

You can show instructions, not a prompt. There is no API to trigger Add to Home Screen. What works is a small illustrated hint pointing at the Share button, shown only to iOS Safari visitors who have not already installed — detectable via navigator.standalone.

Why does it work on my iPad but not my iPhone?

Usually a version difference rather than a device one. Check the iOS version on both: several web-app behaviours, push notifications in particular, landed in 16.4 and are simply absent below it.