PWA Installation & Add to Homescreen

Also Known As

TL;DR

Explanation

PWA installation criteria (Chrome): HTTPS, registered service worker, valid Web App Manifest (name, icons 192px+512px, start_url, display: standalone). The beforeinstallprompt event fires when the browser decides the app is installable — capture it to show a custom install button rather than relying on the browser's default banner. iOS: does not support the beforeinstallprompt event — you must show manual instructions. Installed PWAs: get their own window, appear in task switcher, have their own icon, and can be launched from home screen without browser UI.

Common Misconception

Why It Matters

Common Mistakes

• Not handling iOS separately — Safari does not support beforeinstallprompt; show a manual instruction banner.
• manifest start_url not served by service worker — breaks offline functionality after installation.
• Icons not including 512px — required for Chrome install prompt.
• Showing install prompt too early — capture the event, but show the UI after demonstrating value.

Code Examples

// Missing manifest fields — not installable:
// manifest.json:
{
    "name": "My App"
    // Missing: icons, start_url, display, theme_color
}
// Result: browser never fires beforeinstallprompt

// Complete manifest:
// manifest.json:
{
    "name": "CodeClarityLab Glossary",
    "short_name": "Glossary",
    "start_url": "/glossary/?source=pwa",
    "display": "standalone",
    "theme_color": "#1a1a2e",
    "background_color": "#1a1a2e",
    "icons": [
        {"src": "/icons/192.png", "sizes": "192x192", "type": "image/png"},
        {"src": "/icons/512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable"}
    ]
}

// Custom install button:
let deferredPrompt;
window.addEventListener('beforeinstallprompt', e => {
    e.preventDefault();
    deferredPrompt = e;
    document.getElementById('install-btn').hidden = false;
});
document.getElementById('install-btn').addEventListener('click', () => {
    deferredPrompt.prompt();
});

References

• ↗ https://web.dev/articles/customize-install

Tags

Related Terms