Como personalizar o tema e a identidade visual da interface do usuário do Element Web em 2026

O Element Web oferece aos usuários que hospedam seus próprios servidores diversas maneiras úteis de integrar o cliente à sua organização, mas o caminho suportado mudou. A atualização importante para as implantações atuais é que o Element Web v1.12.30, lançado no final de setembro de 2026, removeu o caminho legado da API de Módulos e Personalização, que ainda pode ser referenciado em guias antigos. Ao mesmo tempo, a documentação oficial de configuração e temas continua a oferecer suporte à personalização da marca por meio de config.jsontemas personalizados, recursos de autenticação personalizados, páginas incorporadas e a nova API de Módulos para alterações de comportamento mais profundas.

Essa distinção é importante. Se você precisa apenas do nome da sua organização, logotipo de login, plano de fundo da tela de login, links no rodapé, cores padrão e uma página inicial ou de boas-vindas personalizada, geralmente não precisa criar um fork do Element Web. Por outro lado, se você deseja reorganizar os componentes principais da interface do usuário ou inserir lógica de aplicação personalizada, a configuração por si só não é suficiente.

Os exemplos abaixo utilizam o estilo de configuração snake_case atual recomendado pelo Element. A documentação oficial de configuração alerta que a compatibilidade com camelCase será descontinuada, portanto, novas implementações devem evitar a criação de novas identidades visuais com base em nomes de chaves legados. Consulte a documentação oficial de configuração do Element Web , a documentação oficial de temas e o histórico de versões oficial .

O que você pode personalizar sem reconstruir o Element Web

A configuração suportada pelo Element abrange mais opções de personalização da marca do que a maioria dos administradores precisa. Os principais controles são:

Antes de alterar a identidade visual da implantação, registre a aparência atual do Element Web para que você possa comparar o resultado após recarregar a nova configuração.

Passo 1: Comece pelo arquivo config.json da implantação.

O Element Web lê a configuração de `<nome_do_arquivo>` config.jsonou de um arquivo específico do domínio chamado `<nome_do_arquivo>` config.$domain.json. De acordo com a documentação oficial, o arquivo específico do domínio é testado primeiro e não é mesclado com o arquivo de fallback: uma configuração completa é usada ou a outra.

Se você estiver desenvolvendo o Element Web por conta própria, a documentação do projeto recomenda copiar config.sample.jsone personalizar a cópia. Para uma implantação empacotada ou em contêiner, edite ou monte o arquivo de configuração de acordo com o método de empacotamento que você já utiliza. Mantenha um backup antes de fazer qualquer alteração.

Comece com a menor alteração de marca possível:

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

O brandvalor substitui “Element” em diversas strings e locais do aplicativo. Ele não transforma o Element Web em um produto totalmente personalizável; a própria documentação do Element afirma explicitamente que a personalização completa da marca/rótulo próprio não é suportada apenas por meio dessas opções de configuração.

Etapa 2: Personalize a experiência de login e boas-vindas

A tela de autenticação é o local mais visível para tornar uma implantação auto-hospedada mais intencional. Atualmente, o Element documenta quatro propriedades de marca: uma imagem de fundo, um destino de link para um logotipo da marca vinculado, o logotipo do cabeçalho de autenticação e links de rodapé.

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

Use URLs HTTPS estáveis ​​que seus usuários do Element Web possam acessar sem autenticação. Um logotipo ou plano de fundo hospedado atrás de outra barreira de login pode não carregar antes que o usuário do Matrix faça login. Além disso, mantenha o logotipo legível tanto em telas de alta densidade quanto em telas menores, em vez de enviar um arquivo raster enorme e depender do navegador para redimensioná-lo.

Uma página de autenticação personalizada pode alterar o logotipo do cabeçalho, o plano de fundo e os links do rodapé, mantendo intacto o fluxo de login subjacente do Element Web.

Etapa 3: Crie um tema personalizado compatível

Para cores e fontes dentro do cliente, use o formato de tema personalizado do Element em vez de manter uma coleção de seletores CSS frágeis. A documentação de temas oferece suporte a temas personalizados em tempo de execução setting_defaults.custom_themes. Um tema personalizado recebe um nome interno no formato `<nome_do_tema>` custom-{theme.name}; esse é o valor a ser usado em ` <nome_do_tema> default_theme`.

Este exemplo compacto altera as cores de destaque principal, da barra lateral, da lista de salas e da linha do tempo usando as teclas documentadas pelo 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"
        }
      }
    ]
  }
}

O mesmo objeto de tema também pode definir fontes. A documentação atual de temas do Element também expõe um compoundobjeto para sobrescrever tokens semânticos do sistema de design Compound. Essa abordagem é útil quando componentes de interface mais recentes usam tokens Compound em vez de variáveis ​​de cor mais antigas, mas deve ser feita com cautela: sobrescreva apenas os tokens semânticos documentados e teste novamente após as atualizações.

Se você criar temas personalizados claros e escuros, dê a eles nomes diferentes e configure-os is_darkcorretamente. Um tema escuro não deve ser criado simplesmente diminuindo todos os valores RGB; verifique o contraste do texto, os estados da sala selecionada, o texto secundário, as cores de aviso, os contornos de foco, os controles do editor de mensagens e os indicadores de notificação.

Um tema personalizado leve pode alinhar a lista de salas, os destaques e a identidade visual do aplicativo com o sistema visual da organização sem substituir as telas principais do Element Web.

Passo 4: Personalize o conteúdo da página inicial, recarregue a página e verifique.

O Element Web também pode apontar para HTML hospedado externamente para suas páginas de boas-vindas e página inicial. O embedded_pagesobjeto documentado oferece suporte a `<head>` welcome_urle `<head> home_url`. Uma login_for_welcomeflag separada pode fazer com que o formulário de login funcione como a página de boas-vindas; quando essa flag está ativada, o welcome_urlcaminho normal é desabilitado.

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

Utilize páginas incorporadas para integração específica da organização, informações sobre uso aceitável, links para documentação interna ou uma mensagem concisa sobre o status do serviço. Trate-as como conteúdo da web: minimize as dependências, sirva-as com segurança e assegure-se de que permaneçam disponíveis independentemente do servidor principal do Matrix.

Após fazer alterações config.json, recarregue o Element Web. A documentação oficial afirma que uma atualização do navegador é suficiente para implantações na web, enquanto o Element Desktop precisa ser completamente fechado — incluindo qualquer processo na bandeja do sistema — e reiniciado. Se as suas alterações aparecerem de forma inconsistente, verifique o cache antes de presumir que o JSON está incorreto. O README de implantação na web do Element menciona especificamente que /config.*.json`<head> /i18n`, ` /version<body>`, `<head>` e ` /index.html<body>` não devem ser armazenados em cache e recomenda a revalidação da página raiz. Consulte o README oficial de implantação na web do Element .

Teste os modos de personalização claro e escuro, caso ofereça ambos. Verifique a navegação, os destaques da sala, o contraste do texto, os anexos e o editor de mensagens — não apenas a tela de login.

Quando o arquivo config.json não é suficiente

Tutoriais antigos podem sugerir a substituição de módulos customisations.jsonou a dependência de pontos de personalização legados. Essa não é mais uma base segura para uma nova implementação. A documentação oficial de personalizações indica que esse mecanismo está obsoleto, e as notas de lançamento da versão 1.12.30 de setembro de 2026 registram a remoção da API legada de Módulos e Personalizações.

Para um comportamento mais complexo da aplicação, utilize o sistema de módulos atual do Element Web, descrito no README do projeto, ou mantenha um fork caso a alteração realmente exija controle de versão. Um fork oferece máxima liberdade, mas também torna cada atualização do Element Web sua responsabilidade. Essa troca raramente compensa se sua necessidade se resume a logotipo, cor, texto, conteúdo de boas-vindas ou página inicial.

Um caso extremo relacionado é a arte de pré-visualização do link social. A documentação oficial de configuração observa que o og:imagevalor reside em `static` index.html, e não em ` config.json. Se você precisar alterar essa imagem, ela se torna uma personalização em tempo de compilação ou de arquivo estático, em vez de uma configuração de marca em tempo de execução.

Lista de verificação

• Abra a página de login em uma janela anônima do navegador e confirme se o logotipo de autenticação, o plano de fundo e os links do rodapé carregam sem uma sessão existente.
• Confirme se o aplicativo exibe o brandvalor desejado após o login.
• Verifique se o tema padrão selecionado é carregado para um novo perfil de navegador, e não apenas para uma conta que tenha alterado anteriormente suas configurações de aparência.
• Verifique o texto da lista de salas, as salas selecionadas, os rótulos secundários, as linhas do tempo, os controles do editor de mensagens, os avisos e os estados de foco para garantir um contraste legível.
• Se você utiliza uma página inicial ou de boas-vindas personalizada, teste-a quando a página externa estiver indisponível para entender o comportamento do sistema em caso de falha.
• Verifique o painel de rede do navegador e confirme se o esperado config.jsonestá sendo obtido após a implantação; o cache desatualizado do proxy reverso ou da CDN é um motivo comum para que uma configuração correta pareça não funcionar.
• Após cada atualização do Element Web, teste novamente os temas personalizados e quaisquer integrações da API do módulo com a nova versão antes de implementá-las para todos os usuários.

Resumindo

Para a maioria das personalizações de Element Web auto-hospedadas, mantenha-se na camada de configuração suportada: brand` <module>` branding, ` <module>`, ` default_theme<module>` setting_defaults.custom_themes, `<module>` e ` embedded_pages<module>`. Isso simplifica bastante as atualizações, em comparação com a necessidade de corrigir componentes React ou depender de hooks de personalização legados. Migre para a API de Módulos ou um fork mantido somente quando sua necessidade realmente alterar o comportamento do aplicativo, e não apenas sua aparência.