BrowserUX PWA UI

Bienvenue sur la documentation de BrowserUX PWA UI

BrowserUX PWA UI offre une expérience utilisateur claire, cohérente et personnalisable pour l’installation et la mise à jour de votre PWA, tout en restant léger, autonome et facile à intégrer dans n’importe quel projet, qu’il s’agisse d’une simple page HTML ou d’une application JavaScript moderne.

I. Pourquoi ce Web Component ?

Les processus d’installation et de mise à jour des Progressive Web Apps (PWA) sont aujourd’hui mal intégrés d’un point de vue expérience utilisateur :

  • L’installation repose sur l’événement beforeinstallprompt, qui est discret et rarement déclenché.
  • Les mises à jour se produisent silencieusement en arrière-plan, sans retour visuel, ce qui peut désorienter l’utilisateur.
  • Il n’existe aucune interface native, unifiée ou personnalisable pour guider l’utilisateur dans ces étapes clés.

Ce composant a été conçu pour combler ces lacunes UX :

Il fournit une interface claire, personnalisable et multilingue pour encourager l’installation des PWA et notifier élégamment les mises à jour — avec un comportement UX cohérent entre les navigateurs.

1. Avantages

  • Universel : fonctionne partout (HTML natif, React, Vue, etc.)
  • Sans dépendance : pas besoin de Vite, React ou d’outils modernes
  • Personnalisable : styles via variables CSS, textes via attributs, icônes via slots
  • Multilingue : détecte automatiquement la langue ou permet une surcharge via lang
  • Mode allégé : le Shadow DOM peut être désactivé (no-shadow)
  • Complète l’expérience PWA : installation + mise à jour (interface uniquement, pas de logique)

II. Comment ça fonctionne

Ce composant affiche automatiquement l’interface appropriée selon l’état de votre PWA :

1. Installation

  • Affiche une bannière lorsque l’événement beforeinstallprompt est déclenché par le navigateur.
  • Permet à l’utilisateur d’installer la PWA via un bouton « Installer ».
  • Affiche un message de confirmation une fois l’installation terminée.

2. Mise à jour

  • Détecte automatiquement lorsqu’un nouveau service worker est en attente (registration.waiting).
  • Affiche une bannière avec un bouton « Mettre à jour ».
  • Lors du clic :
    • Le service worker est activé via skipWaiting.
    • L’application se recharge avec window.location.reload().

3. Langue & Personnalisation

  • La langue est déterminée automatiquement selon :
    • 1. L’attribut lang sur le composant (browserux-pwa-ui lang="fr")
    • 2. document.documentElement.lang
    • 3. Par défaut : en
  • Tous les textes sont traduits et peuvent être remplacés via des attributs HTML.
  • Les couleurs peuvent être personnalisées via des variables CSS.
  • Les icônes peuvent être remplacées à l’aide des éléments slot.

III. Installation

Ce composant fournit uniquement l’interface utilisateur pour les étapes d’installation et de mise à jour d’une PWA. Il suppose que votre manifeste et votre service worker sont déjà correctement configurés. 


npm install browserux-pwa-ui

Ou via CDN :


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

Utilisez la version .esm.js si vous intégrez le composant avec un bundler (React, Vue, etc.), et la version .min.js pour une intégration directe en HTML via CDN.

IV. Utilisation

1. Projet moderne avec bundler (Vite, Webpack, etc.)

1. Importez le composant globalement dans votre script principal :


import 'browserux-pwa-ui';

2. Utilisez-le ensuite dans votre HTML :


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

2. React / Next.js

1. Importez dynamiquement le composant dans un useEffect :


import { useEffect } from 'react';

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

2. Utilisez-le ensuite en JSX comme une balise HTML classique :


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

3. Vue 3

1. Importez-le globalement dans votre main.js ou main.ts :


import 'browserux-pwa-ui';

2. Utilisez-le comme un élément HTML natif :


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

4. Angular

1. Importez-le dans main.ts :


import 'browserux-pwa-ui';

2. Ajoutez CUSTOM_ELEMENTS_SCHEMA à votre AppModule :


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

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

5. HTML uniquement (sans bundler)

1. Chargez le script directement depuis un CDN :


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

2. Utilisez la balise où vous le souhaitez :


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

V. Paramètres de browserux-pwa-ui

1. Attributs fonctionnels

Paramètre Type Nom Description
Masquer l’interface d’installation Attribut no-install Masque l’interface d’installation
Masquer l’interface de mise à jour Attribut no-update Masque l’interface de mise à jour
Sans Shadow DOM Attribut no-shadow Désactive le Shadow DOM (styles globaux requis)
Langue forcée Attribut lang="xx" Force la langue affichée (fr, en, es, de, etc.)
Snackbar Attribut snackbar Le bandeau est en mode en mode snackbar (flottant dans un coin de l’écran) pour les résolutions d'écran > 1024px
Snackbar Position Attribut position Positionne le snackbar : top-left, top-right, bottom-left, bottom-right (valeur par défaut : bottom-right)

Si l’attribut lang n’est pas défini, le composant tentera d’utiliser document.documentElement.lang, et utilisera l’anglais (en) par défaut si aucune langue n’est trouvée.

Exemple :


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

2. Traductions de texte

Tous les textes affichés sont automatiquement traduits.
Vous pouvez les remplacer via des attributs HTML :

Attribut Valeur par défaut (exemple en anglais)
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

Exemple


<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>

Langues supportées

Le composant prend en charge les langues suivantes :

  • 🇬🇧 en – Anglais (par défaut)
  • 🇫🇷 fr – Français
  • 🇪🇸 es – Espagnol
  • 🇩🇪 de – Allemand
  • 🇯🇵 ja – Japonais
  • 🇷🇺 ru – Russe
  • 🇵🇹 pt – Portugais
  • 🇮🇹 it – Italien
  • 🇳🇱 nl – Néerlandais

3. Personnalisation visuelle

Slots d’icônes

Nom du slot Utilisation par défaut
close-icon-install Icône de fermeture (bannière d’installation)
close-icon-confirm Icône de fermeture (confirmation)
close-icon-update Icône de fermeture (bannière de mise à jour)
loader-icon Animation de chargement
Exemple

<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>

Variables CSS personnalisables

Vous pouvez personnaliser les couleurs du composant avec des variables CSS, soit via l’attribut style du composant, soit globalement si no-shadow est activé.

Variable CSS Valeur par défaut Utilité
--bux-pwa-banner-bg #0e93f0 Couleur de fond de la bannière
--bux-pwa-banner-color #fff Couleur du texte de la bannière
--bux-pwa-banner-padding 1rem Espacement intérieur de la bannière
--bux-pwa-banner-btn-bg #fff Couleur de fond du bouton
--bux-pwa-banner-btn-color #000 Couleur du texte du bouton
--bux-pwa-banner-btn-hover-bg #000 Couleur de fond au survol du bouton
--bux-pwa-banner-btn-hover-color #fff Couleur du texte au survol du bouton
--bux-pwa-banner-btn-padding 0.8rem 2rem Espacement intérieur du bouton
--bux-pwa-banner-btn-border-radius 2rem Rayon de bordure du bouton
--bux-pwa-snackbar-padding 2rem 2rem 2rem 1rem Espacement intérieur du mode snackbar
--bux-pwa-snackbar-border-radius 1rem Rayon de bordure en mode snackbar
--bux-pwa-loader-bg rgba(0, 0, 0, 0.7) Couleur de fond du loader
--bux-pwa-z-index 1000 Z-index utilisé pour le composant (bannière / loader)
Exemple

<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. Compilation & Développement


npm install
npm run build

Utilise TypeScript + Rollup pour compiler :

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

VII. Licence

Licence MIT, libre d’utilisation, de modification et de distribution.