BrowserUX PWA UI

Welcome to the BrowserUX PWA UI Documentation

BrowserUX PWA UI provides a clear, consistent, and customizable user experience for installing and updating your PWA, while remaining lightweight, self-contained, and easy to integrate into any project, from simple HTML pages to modern JavaScript applications.

I. Why this Web Component?

The installation and update flows of Progressive Web Apps (PWA) are currently poorly integrated from a user experience perspective:

  • Installation relies on the `beforeinstallprompt` event, which is discreet and rarely triggered.
  • Updates happen silently in the background, without any visual feedback, which can confuse users.
  • There’s no native, unified, or customizable interface to guide users through these key steps.

This component was created to fill those UX gaps:

It provides a clear, customizable, and multilingual interface to encourage PWA installation and elegantly notify users of updates — with consistent UX behavior across browsers.

1. Benefits

  • Universal: works everywhere (native HTML, React, Vue, etc.)
  • Zero dependency: no need for Vite, React, or modern tools
  • Customizable: styles via CSS variables, texts via attributes, icons via slots
  • Multilingual: auto-detects language or allows manual override via lang
  • Lightweight mode: Shadow DOM can be disabled (no-shadow)
  • Complements the PWA experience: install + update (UI only, no logic)

II. How It Works

This component automatically displays the appropriate interface based on the state of your PWA:

1.Installation

  • Displays a banner when the `beforeinstallprompt` event is triggered by the browser.
  • Allows the user to install the PWA via an "Install" button.
  • Shows a confirmation message once the installation is complete.

2. Update

  • Automatically detects when a new service worker is waiting (`registration.waiting`).
  • Displays a banner with an "Update" button.
  • Once clicked:
    • The service worker is activated using `skipWaiting`.
    • The application reloads via `window.location.reload()`.

3. Language & Customization

  • The language is determined automatically from:
    • 1. The `lang` attribute on the component (browserux-pwa-ui lang="en")
    • 2. document.documentElement.lang
    • 3. Defaults to en
  • All texts are translated and can be overridden via HTML attributes.
  • Colors can be customized using CSS variables.
  • Icons can be replaced using slot elements.

III. Installation

This component provides only the user interface for the installation and update flows of a PWA. It assumes your manifest and service worker are already properly configured.


npm install browserux-pwa-ui

Or via CDN:


<script type="module" src="https://unpkg.com/browserux-pwa-ui/dist/browserux-pwa-ui.min.js"></script>

Use the .esm.js version if you're integrating the component via a bundler (React, Vue, etc.), and the .min.js version for direct HTML integration via CDN.

IV. Usage

1. Modern project with bundler (Vite, Webpack, etc.)

1. Import the component globally in your main script:


import 'browserux-pwa-ui';

2. Then use it in your HTML:


<browserux-pwa-ui></browserux-pwa-ui>

2. React / Next.js

1. Dynamically import the component inside a useEffect:


import { useEffect } from 'react';

useEffect(() => {
  import('browserux-pwa-ui');
}, []);

2. Then use it in JSX as a regular HTML tag:


<browserux-pwa-ui></browserux-pwa-ui>

3. Vue 3

1. Import it globally in you main.js or main.ts:


import 'browserux-pwa-ui';

2. Use it like a native HTML element:


<browserux-pwa-ui></browserux-pwa-ui>

4. Angular

1. Import it in main.ts:


import 'browserux-pwa-ui';

2. Add CUSTOM_ELEMENTS_SCHEMA to your AppModule:


import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}

5. HTML only (No bundler

1. Load the script directly from a CDN:


<script type="module" src="https://unpkg.com/browserux-pwa-ui/dist/browserux-pwa-ui.min.js"></script>

2. Use the tag wherever you want:


<browserux-pwa-ui></browserux-pwa-ui>

V. browserux-pwa-ui Parameters

1. Functional Attributes

Parameter Type Name Description
Hide Install UI Attribute no-install Hides the installation interface
Hide Update UI Attribute no-update Hides the update interface
No Shadow DOM Attribute no-shadow Disables Shadow DOM (global styles required)
Forced Language Attribute lang="xx" Forces the displayed language (fr, en, es, de, etc.)
Snackbar Attribute snackbar The banner is displayed in snackbar mode (floating in a screen corner) for screen resolutions greater than 1024px
Snackbar Position Attribute position Positions the snackbar: top-left, top-right, bottom-left, bottom-right (default: bottom-right)

If lang is not defined, the component will try to use document.documentElement.lang, and fallback to English (en) if none is found.

Example:


<browserux-pwa-ui
    no-update
    no-shadow
    lang="fr"
></browserux-pwa-ui>

2. Text Translation

All displayed texts are automatically translated.
You can override them using HTML attributes:

Attribute Default (example: English)
text-install-title Install this application
text-install-message Download our free app. It takes no space…
text-install-button Install
text-installed-title Application installed!
text-update-title An update is available
text-update-button Update

Example


<browserux-pwa-ui
    text-install-title="Ajoutez ce site sur votre écran d'accueil"
    text-update-button="Redémarrer pour mettre à jour"
></browserux-pwa-ui>

Supported Languages

The component supports the following languages:

  • 🇬🇧 en – English (default)
  • 🇫🇷 fr – French
  • 🇪🇸 es – Spanish
  • 🇩🇪 de – German
  • 🇯🇵 ja – Japanese
  • 🇷🇺 ru – Russian
  • 🇵🇹 pt – Portuguese
  • 🇮🇹 it – Italian
  • 🇳🇱 nl – Dutch

3. Visual Customization

Icon Slots

Slot name Default usage
close-icon-install Close icon (install prompt)
close-icon-confirm Close icon (confirmation)
close-icon-update Close icon (update prompt)
loader-icon Loading animation
Example

<browserux-pwa-ui
    <svg slot="close-icon-update" viewBox="0 0 24 24" width="24"><path d="M6 6L18 18M6 18L18 6"/></svg>
    <svg slot="loader-icon" viewBox="0 0 24 24" width="24"><circle cx="12" cy="12" r="10" stroke="orange" fill="none"/></svg>
></browserux-pwa-ui>

CSS Custom Properties

You can customize the component’s colors using CSS variables, either directly in the component’s style attribute or globally if no-shadow is enabled.

CSS Variable Default Value Description
--bux-pwa-banner-bg #0e93f0 Banner background color
--bux-pwa-banner-color #fff Banner text color
--bux-pwa-banner-padding 1rem Inner padding of the banner
--bux-pwa-banner-btn-bg #fff Button background color
--bux-pwa-banner-btn-color #000 Button text color
--bux-pwa-banner-btn-hover-bg #000 Button background on hover
--bux-pwa-banner-btn-hover-color #fff Button text color on hover
--bux-pwa-banner-btn-padding 0.8rem 2rem Padding inside the install/update button
--bux-pwa-banner-btn-border-radius 2rem Button border radius
--bux-pwa-snackbar-padding 2rem 2rem 2rem 1rem Inner padding for snackbar layout
--bux-pwa-snackbar-border-radius 1rem Border radius in snackbar mode
--bux-pwa-loader-bg rgba(0, 0, 0, 0.7) Loader background color
--bux-pwa-z-index 1000 Z-index used for the component (banner / loader)
Example

<browserux-pwa-ui
    style="
        --bux-pwa-color-primary: #007bff;
        --bux-pwa-color-light: #f8f9fa;
        --bux-pwa-color-primary-opacity: rgba(0, 123, 255, 0.8);
    "
></browserux-pwa-ui>

VI. Build & Development


npm install
npm run build

Use TypeScript + Rollup to build:

  • dist/browserux-pwa-ui.esm.js
  • dist/browserux-pwa-ui.umd.js
  • dist/browserux-pwa-ui.d.ts

VII. License

MIT License, free to use, modify, and distribute.