Para uma implantação auto-hospedada do Element Web, defina o nome do aplicativo e o tema padrão em seu arquivo `app.json` config.json, e use as brandingopções documentadas para o logotipo de login, plano de fundo, link do logotipo e links do rodapé. Para cores personalizadas, defina um tema em `application.json` setting_defaults.custom_themese indique default_themeo nome dele custom-. Essas configurações personalizam o Element, mas não o transformam em um produto totalmente de marca branca.
Saiba quais controles de marca você precisa.
A configuração do Element separa a identidade do produto, os temas de cores e os recursos da página. Escolha a menor alteração que atenda ao seu objetivo:
| Objetivo | Configuração | O que ele altera |
| Mostre o nome do seu serviço | brand | Nome do aplicativo em várias strings e locais |
| Defina um tema inicial claro, escuro ou personalizado. | default_theme | Tema de cores padrão para a implantação |
| Alterar a aparência da tela de login e boas-vindas | branding | Logotipo da página de autenticação, plano de fundo, link do logotipo e links do rodapé. |
| Defina cores e fontes personalizadas | setting_defaults.custom_themes | Opções de tema, como marcadores de cor e famílias de fontes. |
Verificado: A documentação do Element afirma que ele suporta algumas personalizações, mas não a reformulação completa da marca ou a criação de rótulos privados. Implicação prática: a alteração brandnão substituirá todos os logotipos, ícones, imagens ou referências de produtos. Se você precisar alterar todos os elementos visuais e textos, espere ter que manter uma versão personalizada e verificá-la novamente após as atualizações. Comece listando os elementos de interface exatos que seus usuários precisam ver antes de optar por uma abordagem que dependa apenas da configuração.
Atualize a configuração implantada com segurança.
O Element Web lê config.jsono arquivo de configuração na inicialização. Faça um backup do arquivo atual e edite-o no local para manter as configurações necessárias, como o servidor doméstico padrão. Para um arquivo tarball de lançamento, o arquivo está no diretório web implantado; o pacote Debian usa o diretório `/etc/element.conf` /etc/element-web/config.json. Com o Docker, monte sua configuração em `/etc/element.conf` /app/config.json. O local correto depende de como você instalou o Element, portanto, verifique seu método de implantação antes de editar.
Adicione as seguintes chaves ao objeto JSON existente, combinando-as com quaisquer configurações já presentes. Não cole este texto como substituto da configuração completa:
{
"brand": "Northstar Chat",
"default_theme": "dark",
"permalink_prefix": "https://chat.example.org",
"branding": {
"logo_link_url": "https://example.org",
"auth_header_logo_url": "https://chat.example.org/assets/logo.svg",
"welcome_background_url": "https://chat.example.org/assets/welcome.jpg",
"auth_footer_links": [
{ "text": "Help", "url": "https://example.org/help" },
{ "text": "Privacy", "url": "https://example.org/privacy" }
]
}
}
Substitua o nome de exemplo, os nomes de host e os recursos pelos seus próprios. brandIsso altera o nome do aplicativo em vários locais; permalink_prefixfaz com que os links permanentes compartilhados apontem para sua implantação do Element em vez de matrix.to. As entradas de logotipo e plano de fundo são URLs carregadas pelo navegador. Sirva-as via HTTPS a partir de um local acessível aos seus usuários e confirme se os controles de acesso, a política de segurança de conteúdo e o cache não as bloqueiam. A documentação não especifica um tamanho de imagem universal para o logotipo de autenticação; portanto, visualize seu recurso real em vez de assumir uma dimensão fixa.
Depende da implantação: um arquivo de configuração afeta a instância do Element Web que o hospeda. Ele não altera o app.element.ioserviço oficial nem modifica automaticamente os aplicativos móveis ou de desktop independentes do Element. Faça a edição no host ou contêiner que hospeda sua própria instância.
Adicione um tema de cores personalizado
Para um tema simples de cores e fontes, o Element documenta as definições de temas personalizados em `<template>` setting_defaults.custom_themes. O nome interno do tema é prefixado com `<template> custom-`; use esse nome completo em ` default_theme<template>`. Este exemplo mostra um tema personalizado compacto. É um ponto de partida, não uma paleta completa:
{
"default_theme": "custom-Northstar",
"setting_defaults": {
"custom_themes": [
{
"name": "Northstar",
"is_dark": false,
"fonts": {
"general": "Inter, sans-serif",
"monospace": "'Courier New'"
},
"colors": {
"accent-color": "#3157A4",
"primary-color": "#3157A4",
"warning-color": "#B5473C",
"sidebar-color": "#202A3B",
"roomlist-background-color": "#F3F5F8",
"roomlist-text-color": "#202938",
"timeline-background-color": "#FFFFFF",
"timeline-text-color": "#202938"
}
}
]
}
}
Incorpore essas chaves ao seu JSON existente em vez de criar um segundo setting_defaultsobjeto. Mantenha o contraste entre texto, planos de fundo e controles legível tanto no estado normal quanto no estado destacado. A referência de tema do elemento inclui cores opcionais adicionais, matrizes de cores para nome de usuário e avatar, fontes personalizadas e tokens de design Compound. Adicione apenas os valores que você revisou na referência atual; uma paleta incompleta pode fazer com que algumas partes da interface usem os valores padrão.
Equívoco comum: essa configuração default_themedefine o padrão da implantação; a documentação não a descreve como uma política que bloqueia a configuração de aparência de todos os usuários. Se você precisa de um tema estritamente aplicado, verifique esse comportamento na versão exata do Element Web que você utiliza, em vez de presumir que o padrão seja um bloqueio.
Aplique a alteração e verifique o resultado.
- Valide a sintaxe JSON antes de implantá-la. A ausência de uma vírgula ou uma aspa incorreta pode impedir o carregamento da configuração. Mantenha o JSON válido: comentários não são suportados.
- Recarregue a página da web após publicar o arquivo. Se o navegador ainda exibir a marca antiga, tente atualizar a página completamente ou abrir uma janela anônima e verifique se o navegador consegue acessar o URL de cada recurso corretamente.
- Analise a tela de login e a interface após a autenticação. Confirme se o nome do aplicativo, o tema escolhido, o destino do logotipo, o plano de fundo e os links do rodapé estão corretos e verifique o contraste do texto na lista de salas e na linha do tempo.
- Verifique as ferramentas de desenvolvedor do navegador e os logs do servidor web em busca de solicitações de configuração ou recursos com falha. Se você usa uma CDN ou um proxy reverso, limpe ou aguarde o término do cache de configurações e recursos, de acordo com sua configuração.
Para um teste de tema em tempo de execução, as notas de temas do Element descrevem o carregamento de um URL de tema JSON em /devtools"Temas personalizados". Considere isso como um fluxo de trabalho de teste ou do lado do usuário, não como um substituto para a implantação da configuração pretendida em todos os clientes. Para uma implantação sustentável, mantenha a configuração e os recursos sob controle de versão e repita essa verificação ao atualizar o Element Web.
O comportamento descrito aqui segue a documentação oficial de configuração e temas do Element Web, verificada em 10 de outubro de 2026. Consulte as referências da sua versão instalada antes de utilizar qualquer configuração: Referência de configuração do Element Web , Documentação de temas do Element Web e Documentação de instalação do Element Web .