Wie man das Element-Webdesign und die Benutzeroberflächen-Markengestaltung im Jahr 2026 anpasst

Element Web bietet Self-Hostern verschiedene nützliche Möglichkeiten, Kunden in die eigene Organisation zu integrieren. Der unterstützte Weg hat sich jedoch geändert. Die wichtigste Neuerung für bestehende Installationen: Element Web v1.12.30, veröffentlicht Ende September 2026, entfernt den alten Pfad zur Modul- und Anpassungs-API, auf den ältere Anleitungen möglicherweise noch verweisen. Gleichzeitig unterstützt die offizielle Dokumentation zu Konfiguration und Design weiterhin Branding durch config.jsonbenutzerdefinierte Designs, gebrandete Authentifizierungsressourcen, eingebettete Seiten und die neuere Modul-API für tiefgreifendere Verhaltensänderungen.

Diese Unterscheidung ist wichtig. Benötigen Sie lediglich Ihren Firmennamen, Ihr Anmeldelogo, Ihren Anmeldehintergrund, Fußzeilenlinks, Standardfarben und eine gebrandete Startseite oder Willkommensseite, ist es in der Regel nicht nötig, Element Web zu forken. Möchten Sie jedoch Kernkomponenten der Benutzeroberfläche neu anordnen oder benutzerdefinierte Anwendungslogik einfügen, reicht die Konfiguration allein nicht aus.

Die folgenden Beispiele verwenden den von Element empfohlenen Konfigurationsstil snake_case. Die offizielle Konfigurationsreferenz weist darauf hin, dass die Kompatibilität mit älteren camelCase-Varianten zukünftig entfallen wird. Daher sollten neue Implementierungen die Verwendung veralteter Schlüsselnamen für das Branding vermeiden. Weitere Informationen finden Sie in der offiziellen Element-Web-Konfigurationsdokumentation , der offiziellen Dokumentation zum Theme-Design und im offiziellen Versionsverlauf .

Was Sie anpassen können, ohne Element Web neu zu erstellen

Die von Element unterstützte Konfiguration bietet mehr Branding-Optionen, als die meisten Administratoren benötigen. Die wichtigsten Steuerelemente sind:

Bevor Sie das Deployment-Branding ändern, notieren Sie sich das aktuelle Erscheinungsbild von Element Web, damit Sie das Ergebnis nach dem Neuladen der neuen Konfiguration vergleichen können.

Schritt 1: Beginnen Sie mit der config.json-Datei des Deployments.

Element Web liest die Konfiguration entweder aus der Datei `.bashrc` config.jsonoder aus einer domänenspezifischen Datei namens `.bashrc` config.$domain.json. Laut offizieller Dokumentation wird zuerst die domänenspezifische Datei verwendet und nicht mit der Fallback-Datei zusammengeführt: Es wird entweder die eine oder die andere vollständige Konfiguration verwendet.

Wenn Sie Element Web selbst kompilieren, empfiehlt die Projektdokumentation, config.sample.jsondie vorhandene Kopie zu kopieren und anzupassen. Bei einer gepackten oder containerisierten Bereitstellung bearbeiten oder binden Sie die Konfigurationsdatei entsprechend Ihrer verwendeten Paketierungsmethode ein. Erstellen Sie vor Änderungen eine Sicherungskopie.

Beginnen Sie mit der kleinstmöglichen Markenänderung:

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

Dieser brandWert ersetzt „Element“ in verschiedenen Anwendungszeichenfolgen und -stellen. Er macht Element Web jedoch nicht zu einem vollständig individualisierbaren Produkt; die Dokumentation von Element selbst weist ausdrücklich darauf hin, dass ein vollständiges Rebranding/Private Labeling allein durch diese Konfigurationsoptionen nicht unterstützt wird.

Schritt 2: Gestalten Sie das Anmelde- und Begrüßungserlebnis mit Ihrer Marke.

Der Authentifizierungsbildschirm bietet die beste Möglichkeit, einer selbstgehosteten Bereitstellung ein professionelles Erscheinungsbild zu verleihen. Element dokumentiert derzeit vier Branding-Elemente: ein Hintergrundbild, ein Linkziel für ein verlinktes Markenlogo, das Logo im Authentifizierungskopf und Links im Fußbereich.

{
  "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"
      }
    ]
  }
}

Verwenden Sie stabile HTTPS-URLs, die Ihre Element Web-Nutzer ohne Authentifizierung erreichen können. Ein Logo oder Hintergrund, der hinter einer zusätzlichen Anmeldemaske gehostet wird, kann möglicherweise nicht geladen werden, bevor sich der Matrix-Nutzer angemeldet hat. Achten Sie außerdem darauf, dass das Logo sowohl auf hochauflösenden als auch auf kleineren Bildschirmen gut lesbar ist, anstatt eine riesige Rasterdatei hochzuladen und darauf zu vertrauen, dass der Browser sie verkleinert.

Eine individuell gestaltete Authentifizierungsseite ermöglicht die Änderung des Header-Logos, des Hintergrunds und der Footer-Links, während der zugrunde liegende Anmeldevorgang von Element Web unverändert bleibt.

Schritt 3: Erstellen Sie ein unterstütztes benutzerdefiniertes Design

Für Farben und Schriftarten im Client verwenden Sie das benutzerdefinierte Theme-Format von Element, anstatt eine Sammlung fehleranfälliger CSS-Selektoren zu pflegen. Die Dokumentation zur Theme-Verwaltung unterstützt benutzerdefinierte Themes zur Laufzeit setting_defaults.custom_themes. Ein benutzerdefiniertes Theme erhält einen internen Namen im Format `<name>` custom-{theme.name}; dieser Wert wird in `<theme>` verwendet default_theme.

Dieses kompakte Beispiel ändert die Hauptakzent-, Seitenleisten-, Raumlisten- und Zeitleistenfarben mithilfe von Schlüsseln, die von Element dokumentiert werden:

{
  "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"
        }
      }
    ]
  }
}

Dasselbe Themenobjekt kann auch Schriftarten definieren. Die aktuelle Dokumentation zum Thema von Element stellt außerdem ein compoundObjekt zum Überschreiben semantischer Token aus dem Compound-Designsystem bereit. Dieser Ansatz ist hilfreich, wenn neuere Oberflächenkomponenten Compound-Token anstelle älterer Farbvariablen verwenden. Er sollte jedoch mit Vorsicht angewendet werden: Überschreiben Sie nur dokumentierte semantische Token und testen Sie nach Aktualisierungen erneut.

Wenn Sie sowohl helle als auch dunkle benutzerdefinierte Designs erstellen, geben Sie ihnen unterschiedliche Namen und konfigurieren Sie sie is_darkkorrekt. Ein dunkles Design sollte nicht einfach durch Absenken aller RGB-Werte erstellt werden; überprüfen Sie stattdessen den Textkontrast, die Zustände des ausgewählten Raums, sekundäre Texte, Warnfarben, Fokusumrandungen, Steuerelemente des Nachrichteneditors und Benachrichtigungssymbole.

Ein leichtes, benutzerdefiniertes Design kann die Raumliste, die Hervorhebungen und die Anwendungsidentität an das visuelle System einer Organisation anpassen, ohne die Kernbildschirme von Element Web zu ersetzen.

Schritt 4: Startseiteninhalte anpassen, dann neu laden und überprüfen

Element Web kann für seine Willkommens- und Startseite auch auf extern gehostetes HTML verweisen. Das dokumentierte embedded_pagesObjekt unterstützt welcome_urldies home_url. Über ein separates login_for_welcomeFlag kann das Anmeldeformular als Willkommensseite fungieren; ist dieses Flag gesetzt, welcome_urlwird der normale Pfad deaktiviert.

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

Verwenden Sie eingebettete Seiten für organisationsspezifisches Onboarding, Informationen zur zulässigen Nutzung, interne Dokumentationslinks oder kurze Statusmeldungen. Behandeln Sie diese wie Webinhalte: Halten Sie Abhängigkeiten minimal, stellen Sie eine sichere Bereitstellung sicher und gewährleisten Sie die Verfügbarkeit unabhängig vom Matrix-Homeserver.

Nach der Änderung config.jsonladen Sie Element Web neu. Laut der offiziellen Dokumentation reicht für Web-Bereitstellungen ein Neuladen des Browsers aus, während Element Desktop vollständig beendet – inklusive aller im Systemtray laufenden Prozesse – und neu gestartet werden muss. Falls Ihre Änderungen nicht konsistent angezeigt werden, überprüfen Sie den Cache, bevor Sie von einem fehlerhaften JSON-Code ausgehen. Die README-Datei für die Web-Bereitstellung von Element weist ausdrücklich darauf hin, dass die Elemente `<head>` /config.*.json, `<head>` /i18n, /version`<head>` und ` /index.html<head>` nicht zwischengespeichert werden sollten, und empfiehlt die erneute Validierung der Startseite. Lesen Sie die offizielle README-Datei für die Web-Bereitstellung von Element .

Testen Sie sowohl die helle als auch die dunkle Version Ihres Brandings, falls Sie beide anbieten. Prüfen Sie Navigation, Raumdarstellung, Textkontrast, Anhänge und den Nachrichteneditor – nicht nur den Anmeldebildschirm.

Wenn config.json nicht ausreicht

Ältere Tutorials empfehlen möglicherweise, Module über customisations.jsonveraltete Anpassungspunkte zu ersetzen oder darauf zurückzugreifen. Dies ist keine sichere Grundlage mehr für eine neue Bereitstellung. Die offizielle Dokumentation zu Anpassungen kennzeichnet diesen Mechanismus als veraltet, und die Versionshinweise zur Version 1.12.30 vom September 2026 dokumentieren die Entfernung der alten Modul- und Anpassungs-API.

Für komplexere Anwendungsfunktionen nutzen Sie am besten das aktuelle Modulsystem von Element Web, das in der Projekt-README beschrieben ist, oder erstellen Sie einen Fork, falls die Änderung wirklich eine Kontrolle auf Quellcodeebene erfordert. Ein Fork bietet maximale Freiheit, macht aber auch jede Aktualisierung von Element Web zu Ihrer Verantwortung. Dieser Kompromiss lohnt sich selten, wenn Sie lediglich Logo, Farbe, Text, Begrüßungsinhalte oder eine Startseite anpassen möchten.

Ein verwandter Sonderfall betrifft die Vorschaubilder für Social-Media-Links. Die offizielle Konfigurationsdokumentation weist darauf hin, dass der og:imageWert in der statischen Datei index.htmlund nicht in der Konfigurationsdatei gespeichert ist config.json. Wenn Sie dieses Bild ändern möchten, muss dies zur Build-Zeit oder in einer statischen Datei angepasst werden, anstatt als Branding-Einstellung zur Laufzeit zu erfolgen.

Prüfliste

• Öffnen Sie die Anmeldeseite in einem privaten Browserfenster und vergewissern Sie sich, dass das Authentifizierungslogo, der Hintergrund und die Fußzeilenlinks auch ohne bestehende Sitzung geladen werden.
• Prüfen Sie, ob die App brandnach dem Login den gewünschten Wert anzeigt.
• Prüfen Sie, ob das ausgewählte Standarddesign für ein neues Browserprofil geladen wird, nicht nur für ein Konto, das zuvor seine Darstellungseinstellungen geändert hat.
• Prüfen Sie den Text der Raumliste, die ausgewählten Räume, die sekundären Beschriftungen, die Zeitleisten, die Steuerelemente des Nachrichtenverfassers, die Warnungen und die Fokuszustände auf guten Lesbarkeitskontrast.
• Wenn Sie eine benutzerdefinierte Startseite oder Willkommensseite verwenden, testen Sie diese, wenn die externe Seite nicht verfügbar ist, um den Fehlermodus zu verstehen.
• Überprüfen Sie das Netzwerk-Panel des Browsers und vergewissern Sie sich, dass die erwarteten Daten config.jsonnach der Bereitstellung abgerufen werden; veraltete Reverse-Proxy- oder CDN-Zwischenspeicherung ist ein häufiger Grund dafür, dass eine korrekte Konfiguration scheinbar nicht funktioniert.
• Nach jedem Element Web-Upgrade sollten benutzerdefinierte Themes und alle Module-API-Integrationen erneut mit der neuen Version getestet werden, bevor sie für alle Benutzer freigegeben werden.

Fazit

Für die meisten selbstgehosteten Element Web-Branding-Lösungen empfiehlt es sich, die unterstützte Konfigurationsebene zu verwenden: brand`<configuration>`, branding` default_theme<configuration>` setting_defaults.custom_themes, `<configuration>` und embedded_pages`<configuration>`. Dadurch werden Aktualisierungen deutlich einfacher als durch das Patchen von React-Komponenten oder die Verwendung veralteter Anpassungsmechanismen. Wechseln Sie erst dann zur Modul-API oder einem gepflegten Fork, wenn Ihre Anforderungen tatsächlich das Anwendungsverhalten und nicht nur das Erscheinungsbild ändern.