Jim Nielsen’s Blog Verified ($10/year for the domain)
Theme: This feature requires JavaScript as well as the default site fidelity (see below).

Controls the level of style and functionality of the site, a lower fidelity meaning less bandwidth, battery, and CPU usage. Learn more.

Getting an Unread Badge Count For the Docked Gmail Web App in macOS

If you didn’t know already, you can now turn webpages into “apps” on your Mac.

I’ve done this for a few apps already and it works great. I get system-level notifications, unread badge counts, and more!

Except for Gmail.

With Gmail I get notifications but I don’t get application badges for indicating when I have unread emails — which, for an email application, is kind of vital.

When I look at my dock[1]:

Screenshot of macOS dock with Gmail app and no app badge.

Or when I’m tabbing between windows:

Screenshot of macOS tab switcher with the Gmail app and no app badge.

I can’t tell if there’s something I need to see in my inbox!

My first thought was, “This is Gmail. If the other web apps I’ve installed support app badges, surely Gmail must too. It’s probably a problem on my end.”

So I searched the internet for a solution, but I found nothing[2].

So I asked about it on Mastodon and Thomas Steiner responded by informing me it wasn’t my problem but Gmail’s because they didn’t support the badge API. And apparently there’s a workaround to this for Chrome Shortcuts via a Chrome extension.

Curious, I started looking at the code behind the extension and realized the workaround was really straightforward.

If you look at the script that runs, it’s basically just polling a Gmail endpoint every few seconds which returns XML that contains the unread count of your inbox. Then it uses navigator.setAppBadge to trigger the system-level notification badge.

This made me realize the Chrome extension’s “workaround” wasn’t a Chrome-specific trick but a Gmail-specific trick — which meant that same code should work in Safari too.

So I tried it. I opened my desktop web app, opened the Safari devtools[3], and copy/pasted the script into the console — and it worked!

Hooray for what Dave called the patchability of the open web.

It’s kind of fascinating that all it’s doing is running navigator.setAppBadge. For whatever reason, there’s something extremely satisfying about toggling a web API and seeing a (traditionally) system-level feature come to life.

Screenshot of macOS dock with the Gmail web app and an app badge indicating the unread count in the inbox.

Now when I’m looking at my dock:

Screenshot of macOS tab switcher with the Gmail web app and an app badge indicating the unread count in the inbox.

Or tabbing between windows:

Animated gif of the Safari devtools console using `navigator.setAppBadge` to turn on/off notification counts for a web app in the dock.

I can see if there’s something to look at in my inbox.

Granted, this breaks when the web app reloads, so you’d have to manually re-run this script again yourself (especially since Safari isn’t allowing web extensions in web apps).

If only browsers allowed users to run their own custom scripts on a per-domain basis (R.I.P. Greasemonkey).

Hopefully Gmail adds support for this feature soon.

  1. If you’re looking for a nice collection of icons for your web apps on macOS, try macosicons.com. You’ll have to select “iOS” icons because you need the full-bleed artwork, but there’s some decent alternatives in there to make your dock prettier. ↩
  2. Mark Otto has a great write-up on some of the technical details a web developer like me would want to know about web apps in macOS. ↩
  3. To open the devtools for a web app you can’t just hit CMD + Option + I. Instead, you have top open, go to the “Develop” menu, find your computer, and then choose the web app from the list in the flyout menu. ↩