react-pwa-hazhtech

The simplest way to add PWA install prompts and status tracking to your React app.

Features

• One-line install button — drop <PWAInstallButton /> anywhere, it handles everything
• Status tracking — know if your app is installable, installed, or running standalone
• TypeScript — full type definitions included
• Lightweight — no runtime dependencies, tree-shakeable (CJS + ESM)
• Works everywhere — Chrome, Edge, Safari (iOS 14.5+), Firefox Android

Installation

npm install react-pwa-hazhtech

Quick Start

1. Wrap your app

import { PWAProvider } from 'react-pwa-hazhtech';

function Root() {
  return (
    <PWAProvider>
      <App />
    </PWAProvider>
  );
}

2a. Drop in the install button (zero config)

import { PWAInstallButton } from 'react-pwa-hazhtech';

function Navbar() {
  return (
    <nav>
      <PWAInstallButton className="install-btn">
        Add to Home Screen
      </PWAInstallButton>
    </nav>
  );
}

PWAInstallButton renders null automatically when the app is already installed or the browser hasn't offered a prompt yet — no extra logic needed.

2b. Or use the hook for custom UI

import { usePWA } from 'react-pwa-hazhtech';

function InstallBanner() {
  const { isInstallable, isInstalled, isStandalone, promptInstall } = usePWA();

  if (isInstalled || isStandalone) return <p>✓ App installed</p>;
  if (!isInstallable) return null;

  return (
    <button onClick={promptInstall}>Install App</button>
  );
}

API

<PWAProvider>

Wrap your app root. Captures the browser install event and tracks PWA state.

<PWAProvider
  onInstallPromptAvailable={(event) => console.log('Ready to install')}
  onAppInstalled={() => console.log('Installed!')}
>
  <App />
</PWAProvider>

| Prop | Type | Description | |------|------|-------------| | onInstallPromptAvailable | (event: BeforeInstallPromptEvent) => void | Fires when the browser install prompt is ready | | onAppInstalled | () => void | Fires after the user installs the app |

<PWAInstallButton>

A plug-and-play install button. Invisible when there's nothing to install.

<PWAInstallButton
  className="my-btn"
  style={{ color: 'white' }}
  onInstall={(outcome) => console.log(outcome)} // 'accepted' | 'dismissed'
>
  Install App
</PWAInstallButton>

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | "Install App" | Button label | | className | string | — | CSS class | | style | CSSProperties | — | Inline styles | | onInstall | (outcome: 'accepted' \| 'dismissed') => void | — | Called after the prompt resolves |

usePWA()

Access PWA state and actions anywhere inside <PWAProvider>. Throws a clear error if called outside the provider.

const {
  isInstallable,    // boolean — browser prompt is ready
  isInstalled,      // boolean — app has been installed
  isStandalone,     // boolean — running as installed PWA
  promptInstall,    // () => Promise<{outcome} | null>
  installPromptEvent // BeforeInstallPromptEvent | null
} = usePWA();

Standalone Utilities

Use these outside of React (e.g. in vanilla JS event handlers). <PWAProvider> must be mounted for these to work.

import { triggerPWAInstall, isPWAInstallAvailable, isPWAMode } from 'react-pwa-hazhtech';

// Is the install prompt ready?
if (isPWAInstallAvailable()) { ... }

// Is the app running as an installed PWA?
if (isPWAMode()) { ... }

// Trigger install from anywhere
const result = await triggerPWAInstall();
if (result?.outcome === 'accepted') { ... }

PWA Requirements

Your app needs three things to be installable:

1. Web App Manifest — public/manifest.json

{
  "name": "My App",
  "short_name": "MyApp",
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#000000",
  "background_color": "#ffffff",
  "icons": [
    { "src": "icon-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "icon-512x512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Link it in your HTML:

<link rel="manifest" href="/manifest.json">
<meta name="theme-color" content="#000000">

2. Service Worker — public/sw.js

const CACHE_NAME = 'my-app-v1';

self.addEventListener('install', () => self.skipWaiting());
self.addEventListener('activate', (e) => e.waitUntil(clients.claim()));
self.addEventListener('fetch', (e) => {
  e.respondWith(caches.match(e.request).then(r => r || fetch(e.request)));
});

3. Register the Service Worker

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js');
  });
}

Serve your app over HTTPS (or localhost) — browsers only fire the install prompt on secure origins.

Browser Support

| Browser | Minimum version | |---------|----------------| | Chrome | 68+ | | Edge | 79+ | | Safari | 14.1+ (iOS 14.5+) | | Firefox | 85+ (Android only) |

License

MIT © HazhTech

Contributing

PRs are welcome! Open an issue if you find a bug or have a feature request.

Support the Project

If this library saved you time, consider buying me a coffee!