Platform in Platforms
PWAs on Safari for macOS (Dock apps)
Published
Safari lets you add any open website to the Dock as a web app, starting with macOS Sonoma (14) and Safari 17 (2023-09). It then launches in its own window with a reduced toolbar, keeps its own cookies and website data, and can use service workers, Web Push, notifications, and badging; a web app manifest controls how that Dock app is named and displayed.
How it works
Section titled “How it works”Safari creates the web app from whatever page is open; a manifest is optional and used when present. The user starts the process; the site cannot start it.
Add to Dock
Section titled “Add to Dock”Apple’s support article Use Safari web apps on Mac (requires macOS Sonoma 14 or later) gives the path (English UI): with the site open, choose File > Add to Dock from the menu bar, or click the Share button and choose Add to Dock; edit the name if wanted and click Add. The app is written to the Applications folder inside the user’s home folder and launches from the Dock, Launchpad, or Spotlight. Removing it means dragging that application to the Trash from Go > Home > Applications in the Finder.
What the manifest controls
Section titled “What the manifest controls”With a manifest present, Safari 17 reads display, name, theme_color, and start_url
to shape the app, per the
Safari 17.0 feature post.
Without one, Safari derives the name from the page title and the icon from the site, and
the window still opens as a web app. The user can override both afterwards in the app’s
own Settings window, which also offers Show navigation controls (back, forward, Share,
and extension buttons) and Show color in title bar.
Data, cookies, and extensions
Section titled “Data, cookies, and extensions”At creation Safari copies the site’s cookies into the new app so a cookie-based login carries over; it copies no other storage, and from then on the app shares no history, cookies, website data, or settings with Safari, much like a separate Safari profile. Safari extensions can be turned on per web app from its Settings. Each origin in a Dock app has the WebKit browser-app quota (about 60 % of the disk on macOS 14 and later) and is subject to the same best-effort eviction rules as Safari.
Notifications, push, and badging
Section titled “Notifications, push, and badging”A Dock app can use Web Push, the Notifications API, service workers, and the Badging API.
Notification permission granted inside the web app (not in Safari) is what enables the
red unread badge on the Dock icon, and the app appears under System Settings >
Notifications by its app name. Declarative Web Push, which subscribes through
window.pushManager without a service worker, reached the Mac with macOS 15.5 per the
WebKit announcement.
Examples
Section titled “Examples”A Dock app and a Safari tab run the same code. Check whether each capability is available before calling it.
Badging only when the API exists and the app is installed
Section titled “Badging only when the API exists and the app is installed”setAppBadge() is present in a Dock app but absent in a Safari tab, and a count set while
notifications are not yet allowed is stored and shown later.
async function updateUnreadBadge(count) { const standalone = typeof window.matchMedia === 'function' && window.matchMedia('(display-mode: standalone)').matches;
if (!standalone || typeof navigator.setAppBadge !== 'function') { // Safari tab, or an engine without Badging: show the count in the page title. document.title = count > 0 ? `(${count}) Inbox` : 'Inbox'; return; } if (count > 0) { await navigator.setAppBadge(count); } else { await navigator.clearAppBadge(); }}Keep the page-title fallback even inside the app: a user who denied notifications sees no Dock badge, and the window title is the next most visible place.
Pointing macOS visitors at File > Add to Dock
Section titled “Pointing macOS visitors at File > Add to Dock”There is no install event in Safari, so the hint is the site’s job, and it should appear only in a Safari tab on macOS 14 or later.
const isMacSafariTab = /Macintosh/.test(navigator.userAgent) && /Safari\//.test(navigator.userAgent) && !/Chrome\//.test(navigator.userAgent) && window.matchMedia('(display-mode: browser)').matches;
if (isMacSafariTab) { showHint('Add this site to your Dock: File > Add to Dock');} else { hideHint();}User-agent sniffing cannot tell Sonoma from an older macOS, so word the hint so that it is harmless when the menu item is missing.
Observed behaviour
Section titled “Observed behaviour”The web app’s Settings window is where the manifest’s choices can be overridden and where the two toolbar switches live.
The absence of bookmarks and tabs is by design: the toolbar offers only back, forward, Share, and extension buttons, and Share > Open in Safari hands the page back to the browser.
See also
Section titled “See also”- PWAs on iOS and Safari
- Desktop install
- Badging
- Web Push
- Use Safari web apps on Mac (support.apple.com)
- WebKit Features in Safari 17.0 (webkit.org)
- Meet Declarative Web Push (webkit.org)
Specifications
| Specification | Status |
|---|---|
| None. | |