Comment personnaliser le thème et l'interface utilisateur d'Element Web en 2026

Element Web offre aux hébergeurs de sites web plusieurs moyens efficaces d'intégrer leurs clients à leur organisation, mais la procédure à suivre a évolué. La principale nouveauté pour les déploiements actuels est la suppression, dans Element Web v1.12.30 (sortie fin septembre 2026), de l'ancienne API Modules et Personnalisation, encore mentionnée dans certains guides. La documentation officielle de configuration et de thèmes continue de prendre en charge la personnalisation via config.jsondes thèmes personnalisés, des éléments d'authentification personnalisés, des pages intégrées et la nouvelle API Modules pour des modifications de comportement plus poussées.

Cette distinction est importante. Si vous n'avez besoin que du nom de votre organisation, du logo et de l'arrière-plan de connexion, des liens du pied de page, des couleurs par défaut et d'une page d'accueil personnalisée, il n'est généralement pas nécessaire de dupliquer Element Web. En revanche, si vous souhaitez réorganiser les composants d'interface utilisateur principaux ou injecter une logique applicative personnalisée, la configuration seule ne suffit pas.

Les exemples ci-dessous utilisent le style de configuration snake_case actuellement recommandé par Element. La documentation de configuration officielle indique que la compatibilité avec l'ancien style camelCase est vouée à disparaître ; par conséquent, les nouveaux déploiements doivent éviter de créer une nouvelle identité visuelle autour d'anciens noms de clés. Consultez la documentation officielle de configuration Web d'Element , la documentation officielle sur les thèmes et l' historique des versions .

Que pouvez-vous personnaliser sans reconstruire Element Web ?

La configuration prise en charge par Element offre une personnalisation plus étendue que ce dont la plupart des administrateurs ont besoin. Les principaux contrôles sont :

Avant de modifier l'image de marque du déploiement, enregistrez l'apparence actuelle d'Element Web afin de pouvoir comparer le résultat après le rechargement de la nouvelle configuration.

Étape 1 : Commencez par le fichier config.json du déploiement.

Element Web lit la configuration à partir du config.jsonfichier `config.json` ou d'un fichier spécifique au domaine nommé `config.json` config.$domain.json. Selon la documentation officielle, le fichier spécifique au domaine est utilisé en premier et n'est pas fusionné avec le fichier de secours : une configuration complète est utilisée ou l'autre.

Si vous développez Element Web vous-même, la documentation du projet recommande de copier config.sample.jsonet de personnaliser la copie. Pour un déploiement packagé ou conteneurisé, modifiez ou montez le fichier de configuration selon la méthode de packaging que vous utilisez. Pensez à effectuer une sauvegarde avant toute modification.

Commencez par le plus petit changement de marque possible :

{
  "brand": "Acme Chat",
  "default_theme": "light"
}

Cette brandvaleur remplace « Element » dans plusieurs chaînes de caractères et à différents endroits de l'application. Elle ne transforme pas Element Web en un produit entièrement personnalisé ; la documentation d'Element indique clairement que la personnalisation complète n'est pas prise en charge par ces seules options de configuration.

Étape 2 : Personnaliser l’expérience de connexion et d’accueil

L'écran d'authentification est l'endroit idéal pour donner une impression de cohérence à un déploiement auto-hébergé. Element propose actuellement quatre éléments de personnalisation : une image de fond, un lien vers le logo de la marque, le logo d'en-tête d'authentification et les liens de pied de page.

{
  "brand": "Acme Chat",
  "branding": {
    "welcome_background_url": "https://chat.example.com/assets/login-background.jpg",
    "logo_link_url": "https://www.example.com/",
    "auth_header_logo_url": "https://chat.example.com/assets/acme-logo.svg",
    "auth_footer_links": [
      {
        "text": "Privacy",
        "url": "https://www.example.com/privacy"
      },
      {
        "text": "Support",
        "url": "https://www.example.com/support"
      }
    ]
  }
}

Utilisez des URL HTTPS stables accessibles sans authentification à vos utilisateurs Element Web. Un logo ou un arrière-plan hébergé derrière un système de connexion externe risque de ne pas se charger avant que l'utilisateur Matrix ne se soit connecté. Veillez également à ce que le logo soit lisible aussi bien sur les écrans haute densité que sur les écrans plus petits, plutôt que de télécharger un fichier raster volumineux et de compter sur le navigateur pour le redimensionner.

Une page d'authentification personnalisée peut modifier le logo d'en-tête, l'arrière-plan et les liens de pied de page tout en laissant intact le flux de connexion Element Web sous-jacent.

Étape 3 : Créer un thème personnalisé compatible

Pour les couleurs et les polices côté client, utilisez le format de thème personnalisé d'Element plutôt que de gérer une collection de sélecteurs CSS fragiles. La documentation sur les thèmes prend en charge les thèmes personnalisés dynamiques via `<customtheme>` setting_defaults.custom_themes. Un thème personnalisé reçoit un nom interne au format `<customtheme>`custom-{theme.name} ; c'est cette valeur à utiliser dans `<customtheme>` default_theme.

Cet exemple concis modifie les couleurs principales, la barre latérale, la liste des salles et la chronologie à l'aide des clés documentées par Element :

{
  "default_theme": "custom-Acme Light",
  "setting_defaults": {
    "custom_themes": [
      {
        "name": "Acme Light",
        "is_dark": false,
        "colors": {
          "accent-color": "#2563eb",
          "primary-color": "#1d4ed8",
          "warning-color": "#dc2626",
          "sidebar-color": "#0f172a",
          "roomlist-background-color": "#f8fafc",
          "roomlist-text-color": "#172033",
          "roomlist-text-secondary-color": "#64748b",
          "roomlist-highlights-color": "#ffffff",
          "roomlist-separator-color": "#e2e8f0",
          "timeline-background-color": "#ffffff",
          "timeline-text-color": "#172033",
          "timeline-text-secondary-color": "#64748b",
          "timeline-highlights-color": "#f1f5f9"
        }
      }
    ]
  }
}

Le même objet de thème peut également définir des polices. La documentation actuelle d'Element sur les thèmes expose en outre un compoundobjet permettant de redéfinir les jetons sémantiques du système de conception Compound. Cette méthode est utile lorsque de nouveaux composants d'interface utilisent des jetons Compound au lieu d'anciennes variables de couleur, mais elle doit être utilisée avec précaution : ne redéfinissez que les jetons sémantiques documentés et effectuez des tests après les mises à jour.

Si vous créez des thèmes personnalisés clair et sombre, donnez-leur des noms différents et configurez-les is_darkcorrectement. Un thème sombre ne doit pas être créé en diminuant simplement toutes les valeurs RVB ; vérifiez le contraste du texte, l’état des pièces sélectionnées, le texte secondaire, les couleurs d’avertissement, les contours de focus, les commandes du compositeur de messages et les badges de notification.

Un thème personnalisé léger permet d'aligner la liste des salles, les points forts et l'identité de l'application avec le système visuel d'une organisation sans remplacer les écrans principaux d'Element Web.

Étape 4 : Personnalisez le contenu de votre page d’accueil, puis rechargez et vérifiez.

Element Web peut également pointer vers du HTML hébergé en externe pour ses pages d'accueil et de bienvenue. L' embedded_pagesobjet documenté prend en charge les formulaires de connexion welcome_urlet d' installation home_url. Un login_for_welcomeparamètre distinct permet d'utiliser le formulaire de connexion comme page d'accueil ; lorsque ce paramètre est activé, le welcome_urlchemin d'accès normal est désactivé.

{
  "embedded_pages": {
    "welcome_url": "https://chat.example.com/assets/welcome.html",
    "home_url": "https://chat.example.com/assets/home.html"
  }
}

Utilisez des pages intégrées pour l'accueil des nouveaux employés, les conditions d'utilisation, les liens vers la documentation interne ou un message concis sur l'état du service. Traitez-les comme du contenu web : limitez les dépendances, assurez-vous de leur sécurité et de leur accessibilité indépendante du serveur principal Matrix.

Après avoir effectué des modifications config.json, rechargez Element Web. La documentation officielle indique qu'un simple rafraîchissement du navigateur suffit pour les déploiements web, tandis qu'Element Desktop doit être complètement fermé (y compris tout processus en arrière-plan) et redémarré. Si vos modifications ne s'affichent pas correctement, vérifiez le cache avant de conclure à une erreur dans le JSON. Le fichier README d'Element pour le déploiement web précise que les propriétés `<head>` /config.*.json, /i18n` /version<body>` et `<body>` /index.htmlne doivent pas être mises en cache et recommande de revalider la page racine. Consultez le fichier README officiel d'Element pour le déploiement web .

Testez les modes clair et sombre si vous les proposez. Vérifiez la navigation, la mise en évidence des salles, le contraste du texte, les pièces jointes et l'éditeur de messages, et pas seulement l'écran de connexion.

Quand config.json ne suffit pas

D'anciens tutoriels peuvent vous indiquer de remplacer des modules via customisations.jsondes points de personnalisation hérités ou d'en dépendre. Cette approche n'est plus sûre pour un nouveau déploiement. La documentation officielle sur les personnalisations indique que ce mécanisme est obsolète, et les notes de version de septembre 2026 (v1.12.30) mentionnent la suppression de l'ancienne API Modules et Personnalisation.

Pour une personnalisation plus poussée du comportement de l'application, utilisez le système de modules actuel d'Element Web décrit dans le fichier README du projet, ou créez une branche (fork) si la modification nécessite un contrôle total du code source. Créer une branche offre une liberté maximale, mais vous rend responsable de chaque mise à jour d'Element Web. Ce compromis est rarement avantageux si vos besoins se limitent à un logo, des couleurs, du texte, un message de bienvenue ou une page d'accueil.

Un cas particulier concerne l'illustration de prévisualisation des liens sociaux. La documentation de configuration officielle indique que cette og:imagevaleur se trouve dans le fichier statique index.html, et non config.jsondans le fichier de configuration. Si vous souhaitez modifier cette image, il s'agit d'une personnalisation effectuée lors de la compilation ou dans un fichier statique, et non d'un paramètre de marque à l'exécution.

Liste de vérification

• Ouvrez la page de connexion dans une fenêtre de navigation privée et vérifiez que le logo d'authentification, l'arrière-plan et les liens du pied de page se chargent sans session existante.
• Vérifiez que l'application affiche bien la brandvaleur attendue après la connexion.
• Vérifiez que le thème par défaut sélectionné se charge bien pour un nouveau profil de navigateur, et pas seulement pour un compte dont les paramètres d'apparence ont déjà été modifiés.
• Vérifiez le contraste lisible du texte de la liste des salles, des salles sélectionnées, des étiquettes secondaires, des chronologies, des commandes du compositeur de messages, des avertissements et des états de focus.
• Si vous utilisez une page d'accueil personnalisée, testez-la lorsque la page externe est indisponible afin de comprendre le mode de défaillance.
• Vérifiez le panneau réseau du navigateur et assurez-vous que les données attendues config.jsonsont bien récupérées après le déploiement ; un proxy inverse obsolète ou une mise en cache CDN est une raison fréquente pour laquelle une configuration correcte semble ne pas fonctionner.
• Après chaque mise à jour d'Element Web, testez à nouveau les thèmes personnalisés et toutes les intégrations de l'API Module avec la nouvelle version avant de les déployer auprès de tous les utilisateurs.

En résumé

Pour la plupart des personnalisations Element Web auto-hébergées, privilégiez la couche de configuration prise en charge : brand`<configuration>`, branding` default_theme<configuration>` setting_defaults.custom_themes, `<configuration>` et ` embedded_pages<configuration>`. Cela simplifie considérablement les mises à jour par rapport à la modification de composants React ou à l’utilisation d’anciens hooks de personnalisation. N’optez pour l’API Module ou une branche maintenue que si votre besoin modifie réellement le comportement de l’application plutôt que son apparence.