Bienvenue sur la documentation de BrowserUX Theme Switcher

1. Détection automatique du thème système

Si aucune préférence utilisateur n’est encore définie, le composant détecte automatiquement le thème préféré du système via la règle CSS :

@media (prefers-color-scheme: dark)

2. Stockage de la préférence utilisateur

Lorsque l’utilisateur clique sur le bouton pour basculer de thème, sa préférence (light ou dark) est enregistrée dans localStorage.
Cette préférence sera :

• appliquée automatiquement à la prochaine visite
• prioritaire sur la détection système

1. Le composant web browserux-theme-switcher

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

1. Importez simplement le composant dans votre code :

import 'browserux-theme-switcher';

2. Puis utilisez-le dans votre HTML :

<browserux-theme-switcher></browserux-theme-switcher>

React / Next.js

1. Ajoutez dans votre composant React (souvent dans un useEffect) :

import { useEffect } from 'react';

useEffect(() => {
    import('browserux-theme-switcher');
}, []);

2. Et dans votre JSX

<browserux-theme-switcher></browserux-theme-switcher>

Ajoutez le fichier types/browserux-theme-switcher.d.ts pour un meilleur support TypeScript avec JSX.

Vue 3

1. Ajoutez dans main.js ou main.ts :

import 'browserux-theme-switcher';

2. Utilisez-le comme un composant natif :

<browserux-theme-switcher></browserux-theme-switcher>

Angular

1. Importez dans main.ts :

import 'browserux-theme-switcher';

2. Ajoutez le CUSTOM_ELEMENTS_SCHEMA dans AppModule :

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

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

Intégration sans bundler / script global

1. Ajoutez directement le composant via un CDN :

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

2. Puis :

<browserux-theme-switcher></browserux-theme-switcher>

2. Gestion des styles CSS

Pour que le thème clair ou sombre s’applique à votre page, vous devez définir vos couleurs via des variables CSS. Le composant <browserux-theme-switcher> applique automatiquement un attributdata-theme="dark" ou "light" à l’élément ciblé (par défaut html), ce qui permet de styliser dynamiquement votre interface.

Exemple complet

:root {
    --bux-page-bg: #eaeaea;
    --bux-page-color: #121212;
    --bux-color-primary: #f05e0e;
    --bux-color-secondary: #0e93f0;
    --bux-white: #fff;
}

/** Mode sombre automatique selon les préférences système */
@media (prefers-color-scheme: dark) {
    :root {
        --bux-page-bg: #333;
        --bux-page-color: #eaeaea;
        --bux-color-primary: #eb8a55;
        --bux-color-secondary: #58aae3;
        --bux-white: #444;
    }
}

/** Mode sombre forcé via browserux-theme-switcher */
[data-theme="dark"] {
    --bux-page-bg: #333;
    --bux-page-color: #eaeaea;
    --bux-color-primary: #eb8a55;
    --bux-color-secondary: #58aae3;
    --bux-white: #444;
}

Explications

• :root définit les couleurs par défaut (mode clair).
• @media (prefers-color-scheme: dark) permet de prendre en compte les préférences système si l’utilisateur n’a pas encore choisi de thème.
• [data-theme="dark"] permet de forcer le mode sombre lorsque l’utilisateur clique sur le bouton du browserux-theme-switcher.

Le switcher applique data-theme="dark" ou data-theme="light" sur l’élément ciblé (html par défaut, ou un conteneur via l’attribut target). Vous devez donc appliquer les variables CSS sur le même élément ou un parent commun.

1. Attributs

Ciblage personnalisé (target)

Par défaut, le composant browserux-theme-switcher applique le thème (data-theme="light" ou "dark") sur l’élément html.
Mais vous pouvez personnaliser cette cible grâce à l’attribut target.

Attribut : target

• Type : string (sélecteur CSS valide)
• Valeur par défaut : html
• Effet : applique l’attribut data-theme sur l’élément correspondant

Exemple

<browserux-theme-switcher
    target="#app"
></browserux-theme-switcher>

<div id="app">
    <!-- Le thème s'applique ici -->
</div>

Dans cet exemple, c’est l’élément #app (et non html) qui recevra l’attribut data-theme. Cela permet de limiter le thème à un conteneur spécifique de votre application (utile dans des micro-frontends, app-shells ou widgets embarqués).

Astuce

Assurez-vous que vos styles CSS dépendent bien de [data-theme="dark"] ou [data-theme="light"] sur le bon sélecteur :

#app[data-theme="dark"] {
    --page-bg: #333;
    /* etc. */
}

Si le sélecteur passé dans target ne correspond à aucun élément au moment du rendu, le fallback sera html.

Internationalisation (lang)

Le composant browserux-theme-switcher prend en charge plusieurs langues pour ses libellés accessibles (par exemple : Activer sombre, Switch to light mode, etc.).

Attribut : lang

• Type : string ("en", "fr", "es", "de", "ja", "ru", "pt", "it", "nl")
• Valeur par défaut : auto-détection
• Effet : force la langue utilisée pour les libellés ARIA (aria-label) du switch

Exemple

<browserux-theme-switcher
    lang="fr"
></browserux-theme-switcher>

Le libellé ARIA du bouton sera automatiquement en français :
aria-label="Activer le mode sombre" ou aria-label="Activer le mode clair"

Détection automatique si lang n’est pas défini

Si vous n'indiquez pas lang, le composant suit cette logique :

• 1. Utilise la valeur de lang sur la balise browserux-theme-switcher
• 2. Sinon, regarde la valeur de lang sur la balise html lang="..."
• 3. Sinon, fallback vers "en" (anglais)

Langues intégrées

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

• 🇬🇧 en – English (par défaut)
• 🇫🇷 fr – Français
• 🇪🇸 es – Español
• 🇩🇪 de – Deutsch
• 🇯🇵 ja – 日本語 (Japonais)
• 🇷🇺 ru – Русский (Russe)
• 🇵🇹 pt – Português
• 🇮🇹 it – Italiano
• 🇳🇱 nl – Nederlands

Accessibilité ARIA (data-label-light / data-label-dark)

Le composant browserux-theme-switcher est conçu pour être accessible aux lecteurs d’écran, grâce à des libellés dynamiques (aria-label) qui décrivent l’action du bouton (activer le mode clair ou sombre).

Par défaut, ces libellés sont générés automatiquement en fonction de la langue (via l’attribut lang). Mais vous pouvez surcharger ces textes avec vos propres libellés personnalisés grâce à deux attributs :

Attributs

Exemple

<browserux-theme-switcher
    data-label-light="Activer le thème clair"
    data-label-dark="Passer en mode sombre"
></browserux-theme-switcher>

Résultat :

• En mode clair → aria-label="Passer en mode sombre"
• En mode sombre → aria-label="Activer le thème clair"

Ces attributs sont prioritaires sur la détection automatique de langue (`lang`).

Shadow DOM optionnel (no-shadow)

Par défaut, le composant browserux-theme-switcher utilise le Shadow DOM pour encapsuler son HTML et son CSS. Cela garantit que ses styles internes ne perturbent pas ceux de la page, et inversement.

Mais dans certains cas, notamment pour appliquer des styles globaux ou pour des contraintes spécifiques de framework, il peut être utile de désactiver cette encapsulation.

Attribut : no-shadow

• Type : boolean (présence seule)
• Valeur par défaut : non présent → Shadow DOM activé
• Effet : si présent, le composant est rendu dans le DOM global sans encapsulation

Exemple

<browserux-theme-switcher no-shadow></browserux-theme-switcher>

Ce composant :

• sera rendu dans le DOM classique (pas dans un shadowRoot)
• pourra être stylisé depuis votre CSS global
• héritera plus facilement des styles extérieurs

Quand utiliser no-shadow ?

• Lorsque vous voulez surcharger facilement les styles du composant via CSS global
• Si vous devez thématiser le switcher à partir de variables CSS de la page
• En contexte d’intégration dans un framework (ex. Angular) où le Shadow DOM pose problème
• Pour déboguer plus simplement le rendu dans le DOM

Attention : sans Shadow DOM, le composant est plus sensible aux conflits de styles globaux. À utiliser avec précaution dans les grandes applications.

Personnalisation CSS (style)

Le composant browserux-theme-switcher expose plusieurs variables CSS personnalisables permettant de modifier son apparence sans avoir à surcharger son style interne.

Exemple

<browserux-theme-switcher
    style="
        --bux-switch-width: 60px;
        --bux-switch-height: 32px;
        --bux-switch-bg-color: #222;
        --bux-switch-thumb-color: orange;
        --bux-switch-emoji-size: 1.5rem;"
></browserux-theme-switcher>

• Ces variables peuvent être modifiées dynamiquement selon le thème ([data-theme="dark"]) ou les breakpoints (media queries).
• Elles fonctionnent même si le Shadow DOM est activé, grâce à l’usage des CSS custom properties.

2. Événements

Événement personnalisable (theme-change)

Le composant browserux-theme-switcher déclenche un événement personnalisé nommé theme-change à chaque changement de thème (suite à un clic utilisateur, un chargement initial avec localStorage, etc.).

Cet événement permet à votre application de réagir dynamiquement aux changements de thème (mise à jour du layout, analytics, etc.).

Événement

• Nom : theme-change
• Contenu :l’événement émis est un CustomEvent dont e.detail.theme contient la nouvelle valeur de thème ("light" ou "dark").

Exemple d’écouteur JavaScript

const switcher = document.querySelector('browserux-theme-switcher');

switcher?.addEventListener('theme-change', (e) => {
  console.log('Thème sélectionné :', e.detail.theme);
});

Cas d’usage possibles

• Modifier dynamiquement une classe CSS sur le body
• Déclencher une animation ou une transition
• Stocker le thème dans un contexte global ou service JS
• Traquer les interactions avec un outil d’analytics

L’événement est disponible dès l'initialisation du composant et fonctionne dans tous les contextes (framework ou HTML pur).