Aller au contenu

Appliquer le thème

Utiliser les thèmes intégrés de waka-ui, proposer le mode sombre, puis appliquer le thème Wakastart de l'organisation de l'utilisateur connecté.

GuideDéveloppeur
Durée
20 min
Voir en Markdown

Un thème waka-ui est un jeu de variables CSS rattaché à un identifiant. Le thème actif est indiqué par l'attribut data-theme de l'élément <html>, et le mode sombre par sa classe dark. Ce guide couvre les trois usages : choisir parmi les thèmes intégrés, laisser l'utilisateur basculer en mode sombre, et appliquer le thème que Wakastart a retenu pour lui.

Avant de commencer

Proposer les thèmes intégrés

waka-ui embarque six thèmes, définis dans sa feuille de style : default, forest, twilight, sunset, monochrome et perpetuity. Chacun a une version claire et une version sombre.

  1. Déclarez dans la configuration de WakaProvider les thèmes que vous proposez :

    TSX
    theme: {
      defaultTheme: "default",
      themes: [
        { id: "default", label: "Par défaut", previewColor: "#1e293b" },
        { id: "forest", label: "Forêt", previewColor: "#2d7a2d" },
        { id: "twilight", label: "Crépuscule", previewColor: "#8b5cf6" },
      ],
      enableSystem: true,
    },

    id doit correspondre à un thème défini en CSS ; label et previewColor servent à l'affichage dans le sélecteur.

  2. Placez un sélecteur et un interrupteur de mode sombre, par exemple dans votre en-tête :

    TSX
    "use client";
    
    import { Button, ThemeSelector, useTheme } from "@wakastellar/ui";
    
    export function AppearanceMenu() {
      const { isDarkMode, toggleDarkMode } = useTheme();
    
      return (
        <div className="flex items-center gap-2">
          <ThemeSelector variant="select" />
          <Button variant="outline" onClick={toggleDarkMode}>
            {isDarkMode ? "Mode clair" : "Mode sombre"}
          </Button>
        </div>
      );
    }

    ThemeSelector accepte les variantes default, select, compact et full. toggleDarkMode n'a d'effet que si enableSystem vaut true.

Le thème et le mode choisis sont mémorisés dans le navigateur : l'utilisateur les retrouve à sa prochaine visite.

Appliquer le thème Wakastart de l'utilisateur

Wakastart résout pour chaque utilisateur un thème : le sien s'il en a choisi un, sinon celui de son client, de son réseau ou de l'application (voir Cascade d'habillage). GET /api/me en renvoie les variables dans branding.themeCssVarsLight et branding.themeCssVarsDark.

Pour que les composants waka-ui l'utilisent, écrivez ces variables sous un identifiant de thème qui vous est propre, puis activez-le.

Déclarer l'identifiant du thème

Ajoutez un thème organisation à la configuration et faites-en le thème par défaut :

TSX
theme: {
  defaultTheme: "organisation",
  themes: [{ id: "organisation", label: "Thème de l'organisation" }],
  enableSystem: true,
},

Tant que les variables ne sont pas chargées, ce thème affiche les couleurs claires par défaut de waka-ui, y compris en mode sombre.

Écrire et activer la feuille de style

Créez un composant qui reçoit l'objet branding et l'applique :

TSX
"use client";

import { useEffect } from "react";
import { useTheme } from "@wakastellar/ui";

const THEME_ID = "organisation";

type Branding = {
  themeCssVarsLight?: Record<string, string>;
  themeCssVarsDark?: Record<string, string>;
};

function cssBlock(selector: string, vars: Record<string, string> = {}): string {
  const lines = Object.entries(vars).map(([name, value]) => `  ${name}: ${value};`);
  return lines.length ? `${selector} {\n${lines.join("\n")}\n}` : "";
}

export function OrganisationTheme({ branding }: { branding: Branding | null }) {
  const { changeTheme } = useTheme();

  useEffect(() => {
    if (!branding?.themeCssVarsLight && !branding?.themeCssVarsDark) return;

    const css = [
      cssBlock(`[data-theme="${THEME_ID}"]`, branding.themeCssVarsLight),
      cssBlock(`[data-theme="${THEME_ID}"].dark`, branding.themeCssVarsDark),
    ]
      .filter(Boolean)
      .join("\n\n");

    let style = document.getElementById("organisation-theme") as HTMLStyleElement | null;
    if (!style) {
      style = document.createElement("style");
      style.id = "organisation-theme";
      document.head.appendChild(style);
    }
    style.textContent = css;

    void changeTheme(THEME_ID);
  }, [branding, changeTheme]);

  return null;
}

Les sélecteurs [data-theme="organisation"] et [data-theme="organisation"].dark sont ceux qu'utilisent les thèmes intégrés : vos variables l'emportent ainsi sur les valeurs par défaut, en clair comme en sombre.

Placer le composant

Rendez <OrganisationTheme branding={me?.branding ?? null} /> sous WakaProvider, là où votre application dispose de la réponse de GET /api/me, par exemple dans le layout de la zone connectée.

Important

waka-ui attend chaque couleur sous la forme de trois composantes HSL, sans fonction : --primary: 221.2 83.2% 53.3%. Un thème dont les couleurs sont écrites oklch(…), hsl(…) ou en hexadécimal s'affiche sans couleur dans les composants. Créez vos thèmes Wakastart dans ce format : c'est celui de l'exemple proposé par le Theme Studio de la console (voir Créer un thème CSS).

Les logos, fonds et favicon ne passent pas par waka-ui : appliquez-les comme décrit dans Afficher l'habillage dans votre application.

Vérifier le résultat

  1. Connectez-vous avec un utilisateur dont le client a un thème par défaut : boutons, liens et bordures prennent ses couleurs.
  2. Dans l'inspecteur du navigateur, l'élément <html> porte data-theme="organisation", et le <head> contient une balise <style id="organisation-theme">.
  3. Basculez en mode sombre : les variables du bloc [data-theme="organisation"].dark s'appliquent.

Voir aussi