PWA

The PWA function makes your site installable on a phone or desktop as an app: a web app manifest, home-screen icons generated from one upload, theme colours, and the iPhone meta tags Apple requires.

Overview

Installing a site as an app gives it a home-screen icon, a standalone window with no browser chrome, and — importantly on iPhone — the ability to receive push notifications at all. Apple only delivers web push to installed sites.

This function exists partly so you don't need a third-party PWA plugin. Those plugins register their own service worker at the site root, which is the same thing Push Notifications needs, and the resulting conflict is one of the most common causes of push simply not working.

Key Features

• Web app manifest with your name, colours and display mode
• Home-screen icons derived from a single 512px upload
• iPhone meta tags, including the guided install path Apple requires
• PWA Install (VT) widget with per-platform behaviour
• The button hides itself once the site is installed
• Warns when a conflicting PWA plugin is active

Setup Instructions

Step 1: Enable the Function

1. Navigate to Voxel Toolkit → Functions
2. Find PWA and toggle it on

Step 2: Fill In the Manifest

Open the function's settings:

• App name — the full name, shown during install
• Short name — what fits under a home-screen icon
• Icon — upload one 512×512 PNG; the other sizes are derived from it
• Maskable icon — tick if your icon has padding around the artwork, so Android can crop it to the device's icon shape without clipping
• Theme colour — colours the status bar and title bar
• Background colour — the splash screen while the app opens
• Display — standalone is the usual choice, and the one that looks like an app
• Start URL — where the app opens; leave empty for the home page

Step 3: Add the Install Button

1. Navigate to Voxel Toolkit → Widgets and enable PWA Install (VT)
2. Add the PWA Install (VT) widget wherever you want to prompt installation

The widget adapts to the platform on its own:

• Chrome, Edge, Android — one tap installs the app
• iPhone and iPad — Apple gives no install API, so the button opens a guided "Add to Home Screen" popover
• Already installed — the button hides itself

PWA and Push Notifications on iPhone

On iPhone, web push only works for an installed site. So the order matters:

1. The visitor installs the site via the PWA Install button
2. They open the installed app from the home screen
3. Only then does the push opt-in prompt work

If you support iPhone users, put the install button somewhere they'll see it before you ask them to enable notifications.

Conflicting Plugins

The settings screen checks for other PWA plugins and warns if it finds one active — Progressify, SuperPWA, OneSignal and PWA for WP among them.

Run one PWA implementation, not two. Whichever service worker claims the root scope wins, and the loser's push subscriptions break in ways that are hard to diagnose from the front end.

Troubleshooting

The Install Button Does Nothing

Browsers only offer installation over HTTPS, and only when the manifest and icon are valid. Check that the icon uploaded successfully and that you're testing on the live HTTPS site.

The Button Isn't Showing at All

It hides when the site is already installed. Open the site in a normal browser tab rather than the installed app, or uninstall it and reload.

iPhone Isn't Receiving Push

The site must be installed to the home screen first, and the opt-in must be granted from inside the installed app rather than Safari. See Push Notifications for the rest.

The Icon Looks Cropped on Android

Tick Maskable icon if the artwork runs to the edges, or re-export it with padding.

Requirements

• HTTPS
• One 512×512 PNG icon
• Elementor, for the install button widget
• No other active PWA plugin