How to Customize Element Web Theme and UI Branding in 2026

Element Web gives self-hosters several useful ways to make the client feel like part of their organization, but the supported path has changed. The important update for current deployments is that Element Web v1.12.30, released in late September 2026, removed the legacy Module and Customisation API path that older guides may still reference. At the same time, the official configuration and theming documentation continues to support branding through config.json, custom themes, branded authentication assets, embedded pages, and the newer Module API for deeper behavior changes.

That distinction matters. If you only need your organization name, login logo, login background, footer links, default colors, and a branded home or welcome page, you usually do not need to fork Element Web. If you want to rearrange core UI components or inject custom application logic, configuration alone is not enough.

The examples below use the current snake_case configuration style recommended by Element. The official configuration reference warns that older camelCase compatibility is intended to disappear, so new deployments should avoid building new branding around legacy key names. See the official Element Web configuration documentation, the official theming documentation, and the official release history.

What you can customize without rebuilding Element Web

Element's supported configuration covers more branding than many administrators need. The main controls are:

Before changing deployment branding, record the current Element Web appearance so you can compare the result after reloading the new configuration.

Step 1: Start from the deployment's config.json

Element Web reads configuration from config.json, or from a domain-specific file named config.$domain.json. According to the official documentation, the domain-specific file is tried first and is not merged with the fallback file: one complete configuration is used or the other.

If you are building Element Web yourself, the project documentation recommends copying config.sample.json and customizing the copy. For a packaged or containerized deployment, edit or mount the configuration file according to the packaging method you already use. Keep a backup before changing it.

Start with the smallest branding change possible:

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

Questo brandvalore sostituisce "Element" in diverse stringhe e posizioni dell'applicazione. Non trasforma Element Web in un prodotto completamente personalizzabile con il proprio marchio; la documentazione di Element specifica esplicitamente che la personalizzazione completa con un marchio privato non è supportata esclusivamente tramite queste opzioni di configurazione.

Passaggio 2: Personalizzare l'esperienza di accesso e di benvenuto

La schermata di autenticazione è il punto più visibile in cui far percepire un'implementazione self-hosted come mirata. Element attualmente documenta quattro proprietà di branding: un'immagine di sfondo, un link di destinazione per un logo del marchio collegato, il logo nell'intestazione di autenticazione e i link nel piè di pagina.

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

Utilizza URL HTTPS stabili che gli utenti di Element Web possano raggiungere senza autenticazione. Un logo o uno sfondo ospitati dietro un ulteriore sistema di login potrebbero non caricarsi correttamente prima che l'utente Matrix abbia effettuato l'accesso. Assicurati inoltre che il logo sia leggibile sia su schermi ad alta densità che su schermi più piccoli, anziché caricare un file raster di grandi dimensioni e affidarti al browser per ridimensionarlo.

Una pagina di autenticazione personalizzata con il marchio può modificare il logo dell'intestazione, lo sfondo e i link del piè di pagina, lasciando inalterato il flusso di accesso di base di Element Web.

Passaggio 3: Creare un tema personalizzato supportato

Per i colori e i caratteri all'interno del client, utilizzare il formato del tema personalizzato di Element anziché mantenere una raccolta di fragili selettori CSS. La documentazione sui temi supporta i temi personalizzati in fase di esecuzione tramite setting_defaults.custom_themes. Un tema personalizzato riceve un nome interno nella forma custom-{theme.name}; questo è il valore da utilizzare in default_theme.

Questo esempio compatto modifica i colori dell'accento principale, della barra laterale, dell'elenco delle stanze e della timeline utilizzando le chiavi documentate da 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"
        }
      }
    ]
  }
}

Lo stesso oggetto tema può anche definire i font. La documentazione attuale di Element relativa alla gestione dei temi espone inoltre un compoundoggetto per sovrascrivere i token semantici del sistema di progettazione Compound. Questa soluzione è utile quando i componenti dell'interfaccia più recenti utilizzano i token di Compound anziché le vecchie variabili di colore, ma va adottata con cautela: sovrascrivere solo i token semantici documentati e ripetere i test dopo gli aggiornamenti.

Se create temi personalizzati sia chiari che scuri, assegnate loro nomi diversi e impostateli is_darkcorrettamente. Un tema scuro non dovrebbe essere creato semplicemente abbassando tutti i valori RGB; verificate il contrasto del testo, gli stati della stanza selezionata, il testo secondario, i colori di avviso, i contorni di messa a fuoco, i controlli del compositore di messaggi e i badge di notifica.

Un tema personalizzato leggero può allineare l'elenco delle sale, le funzionalità in evidenza e l'identità dell'applicazione al sistema visivo di un'organizzazione senza sostituire le schermate principali di Element Web.

Passaggio 4: Personalizza il contenuto della home page, quindi ricarica e verifica

Element Web può anche puntare a file HTML ospitati esternamente per le sue pagine di benvenuto e home page. L' embedded_pagesoggetto documentato supporta welcome_urle home_url. Un flag separato login_for_welcomepuò far sì che il modulo di accesso si comporti come pagina di benvenuto; quando questo flag è impostato su true, il welcome_urlpercorso normale viene disabilitato.

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

Utilizzate pagine incorporate per l'onboarding specifico dell'organizzazione, informazioni sull'utilizzo consentito, link alla documentazione interna o un messaggio conciso sullo stato del servizio. Trattatele come contenuti web: riducete al minimo le dipendenze, servitele in modo sicuro e assicuratevi che rimangano disponibili indipendentemente dal server principale di Matrix.

Dopo aver apportato le modifiche config.json, ricarica Element Web. La documentazione ufficiale afferma che un aggiornamento del browser è sufficiente per le implementazioni web, mentre Element Desktop deve essere chiuso completamente, inclusi eventuali processi nella barra delle applicazioni, e riavviato. Se le modifiche vengono visualizzate in modo incoerente, controlla la cache prima di presumere che il JSON sia errato. Il README di Element per le implementazioni web specifica che /config.*.json, /i18n, /version, e /index.htmlnon devono essere memorizzati nella cache e raccomanda di convalidare nuovamente la pagina radice. Consulta il README ufficiale di Element per le implementazioni web .

Se disponibili, testa entrambe le versioni del tema, chiara e scura. Verifica la navigazione, l'evidenziazione delle stanze, il contrasto del testo, gli allegati e l'editor dei messaggi, non solo la schermata di accesso.

Quando config.json non è sufficiente

I tutorial più vecchi potrebbero suggerire di sostituire i moduli tramite customisations.jsonpunti di personalizzazione legacy o di farvi affidamento. Questa non è più una base sicura per una nuova implementazione. La documentazione ufficiale sulle personalizzazioni indica che questo meccanismo è obsoleto e le note di rilascio della versione 1.12.30 di settembre 2026 riportano la rimozione dell'API legacy per moduli e personalizzazioni.

Per un controllo più approfondito del comportamento dell'applicazione, si consiglia di utilizzare l'attuale sistema di moduli di Element Web descritto nel file README del progetto, oppure di mantenere un fork se la modifica richiede effettivamente il controllo a livello di codice sorgente. Un fork offre la massima libertà, ma rende ogni aggiornamento di Element Web una vostra responsabilità. Questo compromesso raramente vale la pena se le vostre esigenze riguardano solo il logo, il colore, il testo, il contenuto di benvenuto o la pagina iniziale.

Un caso limite correlato riguarda l'anteprima dell'immagine del collegamento social. La documentazione di configurazione ufficiale indica che il og:imagevalore risiede in un file statico index.html, piuttosto che in config.jsonun file statico. Se è necessario modificare quell'immagine, si tratta di una personalizzazione in fase di compilazione o di un file statico, anziché di un'impostazione di branding in fase di esecuzione.

Lista di controllo per la verifica

• Apri la pagina di accesso in una finestra di navigazione in incognito e verifica che il logo di autenticazione, lo sfondo e i link del piè di pagina vengano caricati correttamente anche senza una sessione attiva.
• Verifica che l'app visualizzi il brandvalore previsto dopo l'accesso.
• Verifica che il tema predefinito selezionato venga caricato correttamente anche con un nuovo profilo del browser, e non solo per un account che ha precedentemente modificato le proprie impostazioni di aspetto.
• Verifica che il testo dell'elenco delle stanze, le stanze selezionate, le etichette secondarie, le cronologie, i controlli di composizione dei messaggi, gli avvisi e gli stati di focus siano ben leggibili e contrastati.
• Se utilizzi una pagina iniziale o di benvenuto personalizzata, testala quando la pagina esterna non è disponibile per comprendere la modalità di errore.
• Controlla il pannello di rete del browser e verifica che il contenuto previsto config.jsonvenga scaricato dopo la distribuzione; una cache del reverse proxy o della CDN obsoleta è una causa comune per cui una configurazione corretta sembra non funzionare.
• Dopo ogni aggiornamento di Element Web, testa nuovamente i temi personalizzati e le integrazioni API dei moduli con la nuova versione prima di distribuirli a tutti gli utenti.

In conclusione

Per la maggior parte delle personalizzazioni di Element Web self-hosted, è consigliabile attenersi al livello di configurazione supportato: brand, branding, default_theme, setting_defaults.custom_themes, e embedded_pages. Questo semplifica notevolmente gli aggiornamenti rispetto alla modifica dei componenti React o all'utilizzo di hook di personalizzazione obsoleti. Passare all'API dei moduli o a un fork mantenuto solo quando i requisiti modificano effettivamente il comportamento dell'applicazione anziché il suo aspetto.