2026년 Element 웹 테마 및 UI 브랜딩을 맞춤 설정하는 방법

Element Web은 자체 호스팅 사용자에게 클라이언트가 조직의 일부처럼 느껴지도록 하는 여러 유용한 방법을 제공했지만, 지원되는 경로가 변경되었습니다. 현재 배포 환경에 대한 중요한 업데이트는 2026년 9월 말에 출시된 Element Web v1.12.30에서 이전 가이드에서 여전히 참조될 수 있는 레거시 모듈 및 사용자 지정 API 경로가 제거되었다는 점입니다. 동시에 공식 구성 및 테마 문서는 사용자 config.json지정 테마, 브랜드 인증 자산, 임베디드 페이지 및 더 심층적인 동작 변경을 위한 새로운 모듈 API를 통한 브랜딩을 계속 지원합니다.

그 차이점은 중요합니다. 조직 이름, 로그인 로고, 로그인 배경, 바닥글 링크, 기본 색상, 브랜드가 적용된 홈 또는 환영 페이지만 필요한 경우 Element Web을 포크할 필요가 없는 경우가 많습니다. 하지만 핵심 UI 구성 요소를 재배치하거나 사용자 지정 애플리케이션 로직을 삽입하려면 설정만으로는 충분하지 않습니다.

아래 예제는 Element에서 권장하는 최신 snake_case 구성 스타일을 사용합니다. 공식 구성 참조 문서에서는 이전 camelCase 호환성이 곧 사라질 예정이므로, 새로운 배포 시에는 기존 키 이름을 기반으로 새로운 브랜딩을 구축하지 않도록 주의해야 한다고 경고합니다. 자세한 내용은 Element 웹 구성 공식 문서 , 테마 공식 문서 및 릴리스 내역을 참조하십시오 .

Element Web을 다시 빌드하지 않고 사용자 지정할 수 있는 항목

Element에서 지원하는 구성은 대부분의 관리자가 필요로 하는 것보다 더 많은 브랜딩 옵션을 제공합니다. 주요 제어 기능은 다음과 같습니다.

배포 브랜딩을 변경하기 전에 현재 Element Web의 모양을 기록해 두면 새 구성을 다시 로드한 후 결과를 비교할 수 있습니다.

1단계: 배포의 config.json 파일부터 시작합니다.

Element Web은 구성 파일을 `/etc/element.web` config.json또는 `/etc/element.web`이라는 도메인별 파일에서 읽어옵니다 config.$domain.json. 공식 문서에 따르면 도메인별 파일이 먼저 시도되며, 대체 파일과 병합되지 않습니다. 즉, 완전한 구성 파일 중 하나만 사용됩니다.

Element Web을 직접 빌드하는 경우, 프로젝트 문서에서는 복사본을 만들어 config.sample.json사용자 정의하는 것을 권장합니다. 패키지 또는 컨테이너 배포의 경우, 사용 중인 패키징 방식에 따라 구성 파일을 편집하거나 마운트하십시오. 변경하기 전에 백업을 만들어 두십시오.

가장 작은 브랜드 변경부터 시작하세요.

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

이 brand값은 애플리케이션의 여러 문자열 및 위치에서 "Element"를 대체합니다. 하지만 이 값을 사용한다고 해서 Element Web이 완전히 화이트 라벨 제품으로 바뀌는 것은 아닙니다. Element 자체 문서에서도 이러한 구성 옵션만으로는 완전한 리브랜딩/프라이빗 라벨링이 지원되지 않는다고 명시적으로 밝히고 있습니다.

2단계: 로그인 및 환영 화면에 브랜드를 적용하세요

인증 화면은 자체 호스팅 배포가 의도적으로 설계되었음을 가장 잘 보여줄 수 있는 부분입니다. Element는 현재 배경 이미지, 브랜드 로고를 연결할 링크 대상, 인증 헤더 로고, 바닥글 링크 등 네 가지 브랜딩 속성을 문서화하고 있습니다.

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

Element Web 사용자가 인증 없이 접속할 수 있는 안정적인 HTTPS URL을 사용하세요. 다른 로그인 페이지 뒤에 호스팅된 로고나 배경 이미지는 Matrix 사용자가 로그인하기 전에 로드되지 않을 수 있습니다. 또한, 로고를 고해상도 화면과 작은 화면 모두에서 읽기 쉽게 유지해야 하며, 용량이 큰 래스터 파일을 업로드하고 브라우저에서 크기를 줄여주는 방식은 지양해야 합니다.

브랜드 인증 페이지는 기본 Element Web 로그인 흐름을 그대로 유지하면서 헤더 로고, 배경 및 바닥글 링크를 변경할 수 있습니다.

3단계: 지원되는 사용자 지정 테마를 생성합니다.

클라이언트 내부의 색상과 글꼴에는 불안정한 CSS 선택자 모음을 유지하는 대신 Element의 사용자 지정 테마 형식을 사용하세요. 테마 관련 문서에서는 런타임 사용자 지정 테마를 지원합니다 setting_defaults.custom_themes. 사용자 지정 테마는 형식의 내부 이름을 받습니다 custom-{theme.name}. 이 값이 에 사용됩니다 default_theme.

이 간단한 예제는 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"
        }
      }
    ]
  }
}

동일한 테마 객체로 글꼴도 정의할 수 있습니다. Element의 최신 테마 관련 문서에는 compoundCompound 디자인 시스템의 시맨틱 토큰을 재정의하는 객체도 나와 있습니다. 이 방법은 최신 인터페이스 구성 요소가 기존 색상 변수 대신 Compound 토큰을 사용할 때 유용하지만, 신중하게 접근해야 합니다. 문서화된 시맨틱 토큰만 재정의하고 업그레이드 후 다시 테스트하십시오.

밝은 테마와 어두운 테마를 모두 만들 경우, 각각 다른 이름을 지정하고 is_dark올바르게 설정하세요. 어두운 테마는 단순히 모든 RGB 값을 낮추는 것만으로는 만들 수 없습니다. 텍스트 대비, 선택된 방 상태, 보조 텍스트, 경고 색상, 포커스 윤곽선, 메시지 작성기 컨트롤 및 알림 배지 등을 확인해야 합니다.

간단한 사용자 지정 테마를 사용하면 Element Web의 핵심 화면을 교체하지 않고도 회의실 목록, 주요 항목 및 애플리케이션의 아이덴티티를 조직의 시각 시스템과 일치시킬 수 있습니다.

4단계: 홈 콘텐츠를 맞춤 설정한 다음, 페이지를 새로고침하고 확인합니다.

Element Web은 환영 페이지와 홈 화면에 대해 외부에서 호스팅된 HTML을 가리킬 수도 있습니다. 문서화된 객체는 및 를 embedded_pages지원합니다 . 별도의 플래그를 사용하여 로그인 양식을 환영 페이지로 사용할 수 있으며, 이 플래그가 true이면 일반 경로는 비활성화됩니다.welcome_urlhome_urllogin_for_welcomewelcome_url

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

조직별 온보딩, 사용 규칙 정보, 내부 문서 링크 또는 간결한 서비스 상태 메시지에는 임베디드 페이지를 활용하세요. 이러한 페이지는 웹 콘텐츠처럼 취급해야 합니다. 종속성을 최소화하고, 안전하게 제공하며, Matrix 홈서버와 별개로 항상 접근 가능하도록 유지해야 합니다.

변경 후 config.jsonElement Web을 다시 로드하세요. 공식 문서에 따르면 웹 배포의 경우 브라우저 새로 고침만으로 충분하지만, Element Desktop은 트레이 프로세스를 포함하여 완전히 종료한 후 다시 시작해야 합니다. 변경 사항이 일관되게 표시되지 않으면 JSON이 잘못되었다고 단정하기 전에 캐싱 문제를 확인하세요. Element의 웹 배포 README에는 특히 /config.*.json, /i18n, /version, 및 는 /index.html캐시되지 않아야 하며 루트 페이지의 재검증을 권장한다고 명시되어 있습니다. 자세한 내용은 Element 웹 배포 README를 참조하세요 .

밝은 버전과 어두운 버전 모두 브랜딩을 제공하는 경우 두 가지 모두 테스트하세요. 로그인 화면뿐만 아니라 탐색, 회의실 하이라이트, 텍스트 대비, 첨부 파일 및 메시지 작성 화면도 확인해야 합니다.

config.json만으로는 부족할 때

이전 튜토리얼에서는 레거시 사용자 지정 지점을 통해 모듈을 교체하거나 이에 의존하도록 안내할 수 있습니다 customisations.json. 하지만 이는 더 이상 새로운 배포를 위한 안전한 기반이 아닙니다. 공식 사용자 지정 문서에서는 해당 메커니즘이 더 이상 사용되지 않음을 명시하고 있으며, 2026년 9월 v1.12.30 릴리스 노트에는 레거시 모듈 및 사용자 지정 API가 제거되었다고 기록되어 있습니다.

더욱 심층적인 애플리케이션 동작을 구현하려면 프로젝트 README에 설명된 Element Web의 현재 모듈 시스템을 사용하거나, 변경 사항에 소스 코드 수준의 제어가 정말 필요한 경우 포크를 유지 관리하는 것이 좋습니다. 포크를 사용하면 최대한의 자유를 누릴 수 있지만 Element Web의 모든 업그레이드에 대한 책임은 사용자에게 있습니다. 로고, 색상, 문구, 환영 콘텐츠 또는 홈페이지와 같은 간단한 변경만 필요한 경우에는 이러한 장단점을 감수할 가치가 거의 없습니다.

관련된 예외적인 경우 중 하나는 소셜 링크 미리보기 이미지입니다. 공식 설정 문서에 따르면 해당 값은 `<article> `이 아닌 ` og:image<static>`에 저장됩니다 . 따라서 해당 이미지를 변경해야 하는 경우 런타임 브랜딩 설정이 아닌 빌드 타임 또는 정적 파일 사용자 지정이 필요합니다.index.htmlconfig.json

검증 체크리스트

• 개인 정보 보호 모드 브라우저 창에서 로그인 페이지를 열고 기존 세션 없이 인증 로고, 배경 및 바닥글 링크가 제대로 로드되는지 확인하십시오.
• brand로그인 후 앱에 의도한 값이 표시되는지 확인하십시오 .
• 선택한 기본 테마가 이전에 외관 설정을 변경한 계정뿐만 아니라 새 브라우저 프로필에서도 제대로 로드되는지 확인하십시오.
• 가독성을 높이기 위해 객실 목록 텍스트, 선택된 객실, 보조 레이블, 타임라인, 메시지 작성 컨트롤, 경고 및 포커스 상태를 확인하십시오.
• 사용자 지정 홈 페이지 또는 환영 페이지를 사용하는 경우 외부 페이지를 사용할 수 없을 때 테스트하여 오류 발생 원인을 파악하십시오.
• 배포 후 브라우저의 네트워크 패널을 검사하고 예상대로 config.json데이터가 가져와지는지 확인하십시오. 오래된 리버스 프록시 또는 CDN 캐싱은 올바른 구성이 작동하지 않는 것처럼 보이는 일반적인 원인입니다.
• Element Web을 업그레이드할 때마다 사용자 정의 테마와 모든 모듈 API 통합 기능을 새 릴리스에 맞춰 다시 테스트한 후 모든 사용자에게 배포하십시오.

결론적으로

대부분의 자체 호스팅 Element Web 브랜딩의 경우, 지원되는 구성 레이어인 `<configuration> brand`, branding` default_theme<configuration>` setting_defaults.custom_themes, `<configuration>` 을 사용하는 것이 좋습니다 embedded_pages. 이렇게 하면 React 컴포넌트를 패치하거나 기존 사용자 지정 후크에 의존하는 것보다 업그레이드가 훨씬 간단해집니다. 애플리케이션의 외관이 아닌 동작을 실제로 변경해야 하는 경우에만 모듈 API 또는 유지 관리되는 포크로 전환하십시오.