Add To Home Screen (iOS, iPadOS)

:discourse2: Summary Add To Home Screen (iOS, iPadOS) adds a popup for users on iOS devices. This popup is dismissible and will not show up if you are viewing a Discourse forum via PWA.
:hammer_and_wrench: Repository GitHub - discourse/discourse-apple-add-to-homescreen
:open_book: New to Discourse Themes? Beginner’s guide to using Discourse Themes

Install this theme component


This component adds a popup for users on iOS devices. This popup is dismissible and will not show up if you are viewing a Discourse forum via PWA.




Name Description
popup timer How long should the popup wait before appearing? (in milliseconds)
Translation Default
pwa_text Install %{siteTitle} on your iOS device. Tap share and then Add to Home Screen.

This theme includes two settings, one for the text displayed, and one for a timer to decide how long to wait until the popup appears. These settings come with their defaults set.

This popup will only appear for iOS users on an iPhone or an iPad who are not using PWA to view a Discourse forum. It will not appear again if a user clicks the x icon.

Editing the displayed text

You need to take note when editing this area:

If you want to edit this text, and want the siteTitle to remain here, be sure to keep %{siteTitle} in this text wherever you see fit.

:discourse2: Hosted by us? Theme components are available to use on our Standard, Business, and Enterprise plans.

Last edited by @JammyDodger 2024-06-13T11:05:38Z

Check documentPerform check on document:

Fantastic idea! Thank you! The issue always has been and will be discoverability with this feature.


In core for Android we use a trust level >= 1 check for showing the pop-up, which acts like a timer but is better IMO:

I wonder if this component should use the same :thinking:

Also, I’d love to merge both Android and iOS PWA install banners into a single component in core!


I suggest that the default text should mention push notifications, and avoid mentioning “device.”

Perhaps something like:

“Add %{siteTitle} to your Home Screen to sign up for push notifications! Tap share and then Add to Home Screen.”

It’d be especially helpful if the Discourse team did some A/B testing around this, to find language most likely to get users to sign up for push.

Here are questions I have:

  • Is it better to say “Add” or “Install”?
  • Is it better to mention push notifications here, or to delay mentioning them?
  • If we do mention installation, should we say that this is an “app” being installed? A “web app”?
  • iPad has more room. Is it better to use more words?

On iPad, this banner is not great. The banner appears at the bottom of the screen, but the share button is at the top. I see there’s a little up arrow :arrow_up:, as if to indicate “hey, the button’s up in the header” but I doubt that will be enough. (Have y’all done user testing on this? Have you seen it work for non-expert iPad users?)

It also doesn’t help that we’re asking the user to “tap share,” but the button isn’t visibly called “share.” It’s a little box with an arrow.


Years ago, I used to use which would draw a pop-up like this:


I’d love it if Discourse did something more like this.

Now, the flyout is kinda fragile (what if the button moves?), but I think it’s also OK if the button isn’t exactly where the flyout points, as long as it’s in roughly the right place.

Historically, it was also perilous that the button might look different from one version of iOS to the next. But the share button hasn’t changed shape since iOS 7, and there’s no particular reason to think it will change in iOS 17, so I think an approach like this would work on iPad, with a little flyout pointing toward where the Share button probably is in the header bar.


This is good feedback Dan.

I could see the benefit of showing this flyout at the top of the page when an ipad is being used.

To be quit frank, the reason we didn’t include that icon in this version of the component is that this icon is only available in Font-Awesome 6, and Discourse does not currently support that version yet.


This sort of desire is exactly why I set this text to be editable by an admin. Each person may have a different take on what this popup should say, so feel free to edit to your liking.

1 Like

I don’t think I have the power to A/B test it on my forum. Is that something y’all could A/B test?

Does it let the user know why they might want to do that?

1 Like

Im not sure I follow your question. I would venture if they are on the forum already, the reason behind installing it on their iOS device would be self evident.

My point is that Apple users are only familiar with installing apps via the App Store. Very few will understand what a pwa is. Fewer still will know the potential benefit of installation.

Putting browser notifications behind A2HS is a great move on apples part. It completely solves the early issues with notifications on desktop.

How do we let users know what’s in it for them beyond another icon on their Home Screen?


I completely (but I hope politely) disagree. I run a Discourse forum and have it and others added to the Home Screen. I only thought about doing that after discussions here, and haven’t seen any benefits (the notifications don’t work) so have continued to use the Hub app.


I think we might just be both making assumptions here without gathering feedback from admins who have installed this.

That being said, the text is 100% customizable, so if an admin feels the need to further clarify, they can do so quite easily.

My feedback has been specifically from clients, after mentioning that the PWA was a necessary step to enable notifications.

It’s going to vary between communities, but in the era of ‘ask app not to track’ users aren’t as likely to blindly follow instructions without some perceived benefit. Telling a user how to install the PWA without explaining why definitely buries the lede.

I had this issue with a couple of my self-hosted instances and modifying the push notification time window mins to 0 fixed it for me and most of my users. As a side-effect it also makes the behavior closer to how the Hub app notifications work for timing.


I had to add this plugin manually.

I had a blank repository when clicking with the installer.

Sorry about that, it should be fixed now.

1 Like

Nice component! I like how it’s implemented close to where the share buttons are. Agree that we should integrate this into core and the android banner.

I have an old unimplemented mockup from a while ago that might address some thoughts mentioned here:

Screenshot 2023-06-02 at 8.57.38 AM

The idea with the text here :point_up: was to have some sort of clear “what’s in it for me” — and literally show the site logo in an app-like way to make it a little clearer what this is all about.

That was mocked up for Android, which makes things easier because you can include a button that directly adds the PWA to your device.

Unfortunately iOS still requires you to go through their share sheet to get to this action… but I think we can have a button that triggers the share options? (we already do this for clicking the share icon on posts in iOS…)


Not on iOS. You can open a share sheet with navigator.share(), but it doesn’t have the “Add to Home Screen” button on it. To A2HS, the user has to manually click the little share button; hence the need for something like this.

1 Like

Turns out I was just still on an old iOS version (pre-16.4): Live notifications: "Notifications are not supported on this browser. Sorry."