# PWAs on Safari for macOS (Dock apps)

> How web apps install on macOS through Safari Add to Dock since macOS Sonoma and Safari 17, what the manifest controls, and how a Dock app differs from iOS.

Since macOS Sonoma (14) with Safari 17 (2023-09), any website open in Safari can be added
to the Dock as a web app. 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

Safari creates the web app from whatever page is open; a manifest is optional and used
when present. The user, not the site, starts the process.

### Add to Dock

Apple's support article
[Use Safari web apps on Mac](https://support.apple.com/en-us/104996) (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

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](https://webkit.org/blog/14445/webkit-features-in-safari-17-0/).
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

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

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](https://webkit.org/blog/16535/meet-declarative-web-push/).

## Examples

A Dock app and a Safari tab run the same code, so every capability below is probed, not
assumed.

### 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.

```js
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

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.

```js
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

The web app's Settings window is where the manifest's choices can be overridden and where
the two toolbar switches live.

:::observed
Safari web app on macOS Sonoma 14 (English UI): clicking the app's name in the menu bar
and choosing **Settings** opens a sheet with the fields "Application Name", "Application
URL" (with a "Set to Current Page" button), "Icon", and the checkboxes "Show navigation
controls" and "Show color in title bar", plus "Privacy" and "Extensions" tabs. Documented in
Apple's [Use Safari web apps on Mac](https://support.apple.com/en-us/104996).
:::

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

- [PWAs on iOS and Safari](/reference/platforms/ios-safari/)
- [Desktop install](/reference/installation/desktop-install/)
- [Badging](/reference/installation/badging/)
- [Web Push](/reference/notifications/web-push/)
- [Use Safari web apps on Mac](https://support.apple.com/en-us/104996) (support.apple.com)
- [WebKit Features in Safari 17.0](https://webkit.org/blog/14445/webkit-features-in-safari-17-0/) (webkit.org)
- [Meet Declarative Web Push](https://webkit.org/blog/16535/meet-declarative-web-push/) (webkit.org)