Cómo personalizar el tema web y la identidad visual de Element en 2026

Element Web ofrece a los usuarios que se autogestionan varias formas útiles de integrar al cliente en su organización, pero la ruta compatible ha cambiado. La actualización importante para las implementaciones actuales es que Element Web v1.12.30, lanzado a finales de septiembre de 2026, eliminó la ruta de la API de Módulos y Personalización heredada a la que aún pueden hacer referencia algunas guías antiguas. Al mismo tiempo, la documentación oficial de configuración y temas sigue siendo compatible con la personalización de marca mediante config.jsontemas personalizados, recursos de autenticación de marca, páginas integradas y la nueva API de Módulos para cambios de comportamiento más profundos.

Esa distinción es importante. Si solo necesitas el nombre de tu organización, el logotipo de inicio de sesión, el fondo de inicio de sesión, los enlaces del pie de página, los colores predeterminados y una página de inicio o de bienvenida personalizada, normalmente no necesitas modificar Element Web. Si deseas reorganizar los componentes principales de la interfaz de usuario o insertar lógica de aplicación personalizada, la configuración por sí sola no es suficiente.

Los ejemplos que se muestran a continuación utilizan el estilo de configuración snake_case recomendado por Element. La documentación oficial de configuración advierte que la compatibilidad con camelCase desaparecerá, por lo que las nuevas implementaciones deben evitar basar la identidad visual en nombres de claves antiguos. Consulte la documentación oficial de configuración web de Element , la documentación oficial de temas y el historial de versiones oficial .

Qué puedes personalizar sin reconstruir Element Web

La configuración compatible con Element abarca más opciones de personalización de marca de las que muchos administradores necesitan. Los controles principales son:

Antes de cambiar la imagen de marca de la implementación, registre la apariencia actual de Element Web para poder comparar el resultado después de recargar la nueva configuración.

Paso 1: Comience desde el archivo config.json de la implementación.

Element Web lee la configuración desde config.json, o desde un archivo específico del dominio llamado config.$domain.json. Según la documentación oficial, primero se intenta con el archivo específico del dominio y no se combina con el archivo de reserva: se utiliza una configuración completa o la otra.

Si estás compilando Element Web por tu cuenta, la documentación del proyecto recomienda copiar config.sample.jsony personalizar la copia. Para una implementación empaquetada o en contenedores, edita o monta el archivo de configuración según el método de empaquetado que utilices. Realiza una copia de seguridad antes de modificarlo.

Comience con el cambio de marca más pequeño posible:

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

Este brandvalor reemplaza la palabra "Element" en varias cadenas y ubicaciones de la aplicación. No convierte Element Web en un producto totalmente personalizado; la propia documentación de Element indica explícitamente que el cambio de marca completo o la personalización mediante estas opciones de configuración por sí solas no son compatibles.

Paso 2: Personaliza la experiencia de inicio de sesión y bienvenida.

La pantalla de autenticación es el lugar más visible para que una implementación autoalojada parezca intencional. Actualmente, Element documenta cuatro propiedades de marca: una imagen de fondo, un enlace para el logotipo de la marca, el logotipo del encabezado de autenticación y los enlaces del pie de página.

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

Utilice URL HTTPS estables a las que los usuarios de Element Web puedan acceder sin autenticación. Un logotipo o fondo alojado tras un proceso de inicio de sesión externo podría no cargarse antes de que el usuario de Matrix haya iniciado sesión. Además, asegúrese de que el logotipo sea legible tanto en pantallas de alta densidad como en pantallas más pequeñas, en lugar de subir un archivo rasterizado enorme y depender de que el navegador lo redimensione.

Una página de autenticación personalizada puede cambiar el logotipo del encabezado, el fondo y los enlaces del pie de página, manteniendo intacto el flujo de inicio de sesión subyacente de Element Web.

Paso 3: Crea un tema personalizado compatible.

Para colores y fuentes dentro del cliente, utilice el formato de tema personalizado de Element en lugar de mantener una colección de selectores CSS frágiles. La documentación de temas admite temas personalizados en tiempo de ejecución a través de setting_defaults.custom_themes. Un tema personalizado recibe un nombre interno con el formato custom-{theme.name}; ese es el valor que se debe usar en default_theme.

Este ejemplo compacto cambia los colores del acento principal, la barra lateral, la lista de salas y la línea de tiempo utilizando las claves documentadas por 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"
        }
      }
    ]
  }
}

El mismo objeto de tema también puede definir fuentes. La documentación actual sobre temas de Element también incluye un compoundobjeto para sobrescribir los tokens semánticos del sistema de diseño Compound. Esta opción es útil cuando los componentes de interfaz más recientes usan tokens de Compound en lugar de las variables de color antiguas, pero debe aplicarse con precaución: sobrescriba solo los tokens semánticos documentados y vuelva a realizar pruebas después de las actualizaciones.

Si creas temas personalizados claros y oscuros, asígnales nombres diferentes y configúralos is_darkcorrectamente. Un tema oscuro no debe crearse simplemente reduciendo todos los valores RGB; verifica el contraste del texto, los estados de las salas seleccionadas, el texto secundario, los colores de advertencia, los contornos de enfoque, los controles del editor de mensajes y los distintivos de notificación.

Un tema personalizado sencillo puede alinear la lista de salas, los elementos destacados y la identidad de la aplicación con el sistema visual de una organización sin reemplazar las pantallas principales de Element Web.

Paso 4: Personaliza el contenido de la página de inicio, luego recarga y verifica.

Element Web también puede apuntar a HTML alojado externamente para sus experiencias de bienvenida y de inicio. El embedded_pagesobjeto documentado admite welcome_urly home_url. Un indicador independiente login_for_welcomepuede hacer que el formulario de inicio de sesión actúe como página de bienvenida; cuando ese indicador es verdadero, la ruta normal welcome_urlse desactiva.

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

Utilice páginas integradas para la incorporación de nuevos usuarios específica de la organización, información sobre el uso aceptable, enlaces a documentación interna o un mensaje conciso sobre el estado del servicio. Trátelas como contenido web: minimice las dependencias, sírvalas de forma segura y asegúrese de que permanezcan disponibles independientemente del servidor principal de Matrix.

Después de cambiar config.json, recargue Element Web. La documentación oficial indica que una actualización del navegador es suficiente para las implementaciones web, mientras que Element Desktop debe cerrarse por completo (incluido cualquier proceso en la bandeja) y reiniciarse. Si sus cambios aparecen de forma inconsistente, compruebe el almacenamiento en caché antes de asumir que el JSON es incorrecto. El README de implementación web de Element indica específicamente que /config.*.json, /i18n, /version, y /index.htmlno deben almacenarse en caché, y recomienda revalidar la página raíz. Consulte el README oficial de implementación web de Element .

Pruebe ambos estilos de marca, claro y oscuro, si los ofrece. Verifique la navegación, los elementos destacados de la sala, el contraste del texto, los archivos adjuntos y el editor de mensajes, no solo la pantalla de inicio de sesión.

Cuando config.json no es suficiente

Los tutoriales antiguos pueden indicar que se reemplacen los módulos mediante customisations.jsonpuntos de personalización heredados o que se dependa de ellos. Esto ya no constituye una base segura para una nueva implementación. La documentación oficial sobre personalizaciones indica que este mecanismo está obsoleto, y las notas de la versión 1.12.30 de septiembre de 2026 recogen la eliminación de la API de módulos y personalización heredada.

Para un control más profundo del comportamiento de la aplicación, utilice el sistema de módulos actual de Element Web, descrito en el archivo README del proyecto, o bien, cree una bifurcación si el cambio requiere un control a nivel de código fuente. Una bifurcación ofrece máxima libertad, pero también implica que usted será responsable de cada actualización de Element Web. Esta desventaja rara vez compensa si sus requisitos se limitan al logotipo, el color, el texto, el mensaje de bienvenida o la página de inicio.

Un caso particular relacionado es la imagen de vista previa de los enlaces a redes sociales. La documentación de configuración oficial indica que el og:imagevalor reside en static index.html, en lugar de config.json. Si necesita cambiar esa imagen, se convierte en una personalización en tiempo de compilación o de archivo estático en lugar de una configuración de marca en tiempo de ejecución.

Lista de verificación

• Abra la página de inicio de sesión en una ventana de navegación privada y confirme que el logotipo de autenticación, el fondo y los enlaces del pie de página se cargan sin que exista una sesión activa.
• Confirma que la aplicación muestre el brandvalor deseado después de iniciar sesión.
• Verifique que el tema predeterminado seleccionado se cargue correctamente para un nuevo perfil de navegador, y no solo para una cuenta que haya cambiado previamente su configuración de apariencia.
• Compruebe que el texto de la lista de habitaciones, las habitaciones seleccionadas, las etiquetas secundarias, las líneas de tiempo, los controles del editor de mensajes, las advertencias y los estados de enfoque tengan un contraste legible.
• Si utiliza una página de inicio o de bienvenida personalizada, pruébela cuando la página externa no esté disponible para comprender el modo de fallo.
• Inspeccione el panel de red del navegador y confirme que config.jsonse obtiene lo esperado después de la implementación; el almacenamiento en caché obsoleto de un proxy inverso o de una CDN es una razón común por la que una configuración correcta parece no funcionar.
• Tras cada actualización de Element Web, vuelva a probar los temas personalizados y cualquier integración de la API de módulos con la nueva versión antes de implementarlos para todos los usuarios.

En resumen

Para la mayoría de las aplicaciones web Element autohospedadas, manténgase con la capa de configuración compatible: brand, branding, default_theme, setting_defaults.custom_themes, y embedded_pages. Esto simplifica mucho las actualizaciones en comparación con parchear componentes de React o depender de ganchos de personalización heredados. Pase a la API de módulos o a una bifurcación mantenida solo cuando su requisito realmente cambie el comportamiento de la aplicación en lugar de su apariencia.