Bienvenue dans la documentation de BrowserUX Share Button

1. Détection automatique des capacités de partage

Lorsqu’un utilisateur clique sur le bouton :

• Si navigator.share() est pris en charge (généralement sur mobile ou PWA), la fiche de partage native s’ouvre.
• Sinon, une modale personnalisée s’affiche, avec des liens de partage et une option de copie du lien dans le presse-papiers.

2. Résolution des métadonnées

Le composant détermine automatiquement les données à partager :

• Titre : depuis l’attribut title, la balise <title> ou le manifest.
• Texte : depuis l’attribut text, la meta description ou le manifest.
• URL : depuis l’attribut url ou location.href.

Ce comportement permet une intégration immédiate : il suffit d’ajouter le composant dans le HTML.

3. Modale de secours personnalisable

Lorsque le fallback est activé, la modale :

• Affiche uniquement les plateformes activées (email, X, WhatsApp, etc.).
• Présente un encart avec l’icône de l’application, le titre et le lien à partager.
• Permet à l’utilisateur de copier le lien avec un retour visuel (Lien copié !).
• Prend en charge la navigation au clavier et tactile (touche Échap, swipe pour fermer sur mobile).

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

1. Importez le composant globalement dans votre script principal :

import 'browserux-share-button';

2. Utilisez-le ensuite dans votre HTML :

<browserux-share-button></browserux-share-button>

2. React / Next.js

1. Importez dynamiquement le composant à l’intérieur d’un useEffect :

import { useEffect } from 'react';

useEffect(() => {
  import('browserux-share-button');
}, []);

2. Utilisez-le ensuite dans votre JSX comme une balise HTML standard :

<browserux-share-button></browserux-share-button>

Ajoutez un fichier types/browserux-share-button.d.ts pour un meilleur support TypeScript avec JSX.

3. Vue 3

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

import 'browserux-share-button';

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

<browserux-share-button></browserux-share-button>

4. Angular

1. Importez-le dans main.ts :

import 'browserux-share-button';

2. Ajoutez CUSTOM_ELEMENTS_SCHEMA à votre AppModule :

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

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

1. Ciblage personnalisé (url)

Par défaut, le composant browserux-share-button partage l’URL de la page en cours (location.href). Toutefois, vous pouvez remplacer ce comportement en définissant une URL différente avec l’attribut url.

Attribut : url

• Type : string (URL valide)
• Valeur par défaut : location.href
• Effet : spécifie l’URL à transmettre à l’API Web Share native ou aux liens de partage fallback

Exemple

<browserux-share-button
    url="https://example.com/page-to-share"
></browserux-share-button>

Dans cet exemple, un clic sur le bouton partagera https://example.com/page-to-share, quelle que soit l’URL réelle de la page. Cela est utile pour :

• Partager une URL canonique ou raccourcie
• Promouvoir une landing page depuis plusieurs contextes
• Tester différents liens sans modifier l’URL de la page

Conseil

Assurez-vous que l’URL est accessible publiquement et commence par https:// pour garantir la compatibilité avec les services de partage sociaux et natifs.

2. Titre personnalisé (title)

Le titre est utilisé par certaines plateformes de partage comme objet (email) ou titre visible (ex. X/Twitter ou LinkedIn). Par défaut, le composant essaie d’extraire le titre du document ou du manifest de l’application.

Attribut : title

• Type : string
• Valeur par défaut : depuis la balise title ou le manifest
• Effet : fournit un titre lisible dans le contenu partagé

Exemple

<browserux-share-button
    title="Découvrez cet article génial !"
></browserux-share-button>

Dans ce cas, les plateformes comme l’email utiliseront ce texte comme objet, et X/Twitter l’ajoutera au contenu du message.

Comportement par défaut

Si aucun titre n’est fourni :

• 1. Le composant lit la balise title de la page
• 2. Sinon, il essaie de récupérer le champ name du manifest
• 3. Si rien n’est disponible, aucun titre n’est inclus

Quand surcharger le titre

Utilisez un title personnalisé si :

• Le titre de la page est trop générique
• Vous souhaitez mettre en avant un message ou produit spécifique
• Vous partagez une page dans une app shell ou une vue embarquée

Conseil : combinez les attributs title, text et url pour une présentation optimale sur toutes les plateformes.

3. Texte de partage personnalisé (text)

L’attribut text permet de fournir un message ou résumé accompagnant l’URL partagée. Ce contenu est couramment utilisé dans les applications de messagerie, sur les réseaux sociaux, ou dans le corps des e-mails.

Attribut : text

• Type : string
• Valeur par défaut : extraite de la meta description, du manifest (champ description), ou vide
• Effet : ajoute du contexte au contenu partagé, particulièrement utile si l’URL seule n’est pas suffisamment explicite

Exemple

<browserux-share-button
    text="Voici une lecture rapide que tu devrais apprécier."
></browserux-share-button>

Cas d’usage

• Donner une raison de cliquer ou de lire le lien
• Inclure un message promotionnel avec l’URL
• Décrire plus clairement le contenu lié

4. Langue personnalisée (lang)

L’attribut lang permet de contrôler la langue utilisée pour tous les libellés internes, les descriptions ARIA et le contenu de la modale de secours.

Attribut : lang

• Type : string
• Valeur par défaut : déterminée à partir du composant, de la balise html lang ou en par défaut
• Effet : ajuste les contenus internationalisés affichés par le composant

Exemple

<browserux-share-button
    lang="fr"
></browserux-share-button>

Dans cet exemple, tous les libellés comme "Copier le lien" ou les messages d’erreur s’afficheront en français.

Ordre de détection de la langue

• 1. Attribut lang explicite sur le composant
• 2. Sinon, valeur de la balise html lang
• 3. Sinon, valeur par défaut en (anglais)

Langues prises en charge

Le composant prend en charge les langues suivantes pour les libellés accessibles (aria-label) :

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

5. Désactivation du Shadow DOM (no-shadow)

Par défaut, le composant utilise le Shadow DOM pour encapsuler ses styles et sa structure. Vous pouvez désactiver ce comportement en ajoutant l’attribut no-shadow.

Attribut : no-shadow

• Type : boolean (présence seule)
• Effet : rend le contenu du composant dans le Light DOM (sans encapsulation)

Exemple

<browserux-share-button
    no-shadow
></browserux-share-button>

Quand l’utiliser

• Vous souhaitez styliser le composant via du CSS global
• Vous utilisez un framework qui pose problème avec le Shadow DOM
• Vous préférez faciliter l’inspection ou le débogage dans les DevTools

⚠️ Désactiver le Shadow DOM rend le composant plus sensible aux conflits de styles globaux.

6. Désactiver des plateformes de partage (facebook="false", etc.)

L’interface fallback du composant browserux-share-button propose plusieurs options de partage. Si certaines plateformes ne sont pas pertinentes pour votre public ou usage, vous pouvez les désactiver via un simple attribut booléen.

Format

• Nom de l’attribut : identique au nom de la plateforme
• Valeur : "false" (chaîne de caractères)

Plateformes prises en charge

• email
• sms
• x
• facebook
• whatsapp
• linkedin
• telegram
• reddit

Exemple

<browserux-share-button
    facebook="false"
    sms="false"
></browserux-share-button>

7. Manifest personnalisé (manifest-src)

Par défaut, si vous ne renseignez pas explicitement les attributs title ou text, browserux-share-button tente de récupérer les métadonnées depuis le manifest de votre application web.

Le composant recherche :

• name → utilisé comme titre de partage
• description → utilisé comme texte de partage

Cela permet une intégration automatique avec les métadonnées d’une PWA existante.

Attribut : manifest-src

• Type : string (chemin relatif ou URL absolue valide)
• Par défaut : utilise le <link rel="manifest"> présent dans la page
• Effet : remplace l’URL du manifest utilisée pour charger les métadonnées

Exemple

<browserux-share-button
    manifest-src="/custom-manifest.webmanifest"
></browserux-share-button>

Quand l’utiliser

• Votre fichier manifest n’est pas déclaré dans le header de la page
• Vous souhaitez charger des métadonnées depuis un fichier différent (ex : manifest par page)
• Le chemin du manifest par défaut est erroné ou inaccessible

Logique de repli

Si aucun manifest-src n’est spécifié :

• 1. Le composant cherche une balise <link rel="manifest"> dans le <head>
• 2. Si elle existe, il tente de la charger et de la parser
• 3. En cas d’échec, il poursuit avec les valeurs par défaut ou vides

Conseil : le manifest doit être servi avec le bon type MIME (application/manifest+json) et accessible via CORS.