2026年にElement WebテーマとUIブランディングをカスタマイズする方法

Element Web は、セルフホスティングを行うユーザーに、クライアントが組織の一員であるかのように感じさせるための便利な方法をいくつか提供していますが、サポートされるパスが変更されました。現在のデプロイメントにとって重要な更新は、2026 年 9 月下旬にリリースされた Element Web v1.12.30 で、古いガイドでまだ参照されている可能性のある従来のモジュールおよびカスタマイズ API パスが削除されたことです。同時に、公式の設定およびテーマに関するドキュメントではconfig.json、カスタムテーマ、ブランド認証アセット、埋め込みページ、およびより詳細な動作変更のための新しいモジュール API を介したブランディングが引き続きサポートされています。

その違いは重要です。組織名、ログインロゴ、ログイン背景、フッターリンク、デフォルトの色、ブランド化されたホームページまたはウェルカムページだけが必要な場合は、通常、Element Webをフォークする必要はありません。コアUIコンポーネントを再配置したり、カスタムアプリケーションロジックを挿入したりする場合は、設定だけでは不十分です。

以下の例では、Elementが推奨する現在のsnake_case構成スタイルを使用しています。公式構成リファレンスでは、従来のcamelCaseとの互換性は廃止される予定であるため、新規導入時には従来のキー名に基づいた新しいブランディングの構築を避けるよう警告しています。Element Web構成に関する公式ドキュメント、テーマに関する公式ドキュメント、および公式リリース履歴を参照してください。

Element Webを再構築せずにカスタマイズできるもの

Elementがサポートする設定は、多くの管理者が必要とする以上のブランディング機能を網羅しています。主なコントロールは以下のとおりです。

デプロイメントのブランディングを変更する前に、現在のElement Webの外観を記録しておくと、新しい設定を再読み込みした後の結果を比較できます。

ステップ1：デプロイメントのconfig.jsonから始めます

Element Web はconfig.json、またはという名前のドメイン固有ファイルから設定を読み込みますconfig.$domain.json。公式ドキュメントによると、ドメイン固有ファイルが最初に試行され、フォールバックファイルとはマージされません。つまり、完全な設定はどちらか一方のみが使用されます。

Element Webを独自に構築する場合は、プロジェクトドキュメントに記載されているように、既存のファイルをコピーしconfig.sample.jsonてカスタマイズすることをお勧めします。パッケージ化またはコンテナ化された環境でデプロイする場合は、既に使用しているパッケージ化方法に応じて設定ファイルを編集またはマウントしてください。変更する前に必ずバックアップを作成してください。

まずは、可能な限り最小限のブランディング変更から始めましょう。

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

このbrand値は、アプリケーションの複数の文字列および箇所で「Element」という文字列を置き換えます。ただし、これによりElement Webが完全にホワイトラベル製品になるわけではありません。Elementの公式ドキュメントにも明記されているように、これらの設定オプションだけでは完全なリブランディング／プライベートラベル化はサポートされていません。

ステップ2：サインインとウェルカムエクスペリエンスにブランドを付ける

認証画面は、セルフホスト型デプロイメントを意図的に演出する上で最も目立つ場所です。Elementは現在、背景画像、リンクされたブランドロゴへのリンク先、認証ヘッダーのロゴ、フッターリンクという4つのブランディングプロパティを文書化しています。

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

組織固有のオンボーディング、利用規約、内部ドキュメントへのリンク、または簡潔なサービスステータスメッセージには、埋め込みページを使用してください。これらはWebコンテンツとして扱い、依存関係を最小限に抑え、安全に配信し、Matrixホームサーバーとは独立して利用できるようにしてください。

変更後config.json、Element Web を再読み込みしてください。公式ドキュメントでは、Web デプロイメントの場合はブラウザの更新で十分ですが、Element Desktop はトレイ プロセスを含め完全に終了してから再起動する必要があると記載されています。変更が一貫して表示されない場合は、JSON が間違っていると決めつける前にキャッシュを確認してください。Element の Web デプロイメント README には、、、、はキャッシュすべきではないと明記されており、/config.*.jsonルートページの再検証が推奨されています。公式の Element Web デプロイメント README を参照してください。/i18n/version/index.html

ライトモードとダークモードの両方のブランディング設定を提供している場合は、両方をテストしてください。ログイン画面だけでなく、ナビゲーション、ルームのハイライト表示、テキストのコントラスト、添付ファイル、メッセージ作成画面も確認してください。

config.jsonだけでは不十分な場合

古いチュートリアルでは、従来のカスタマイズポイントを使用してモジュールを置き換える、customisations.jsonまたはそれに依存するように指示している場合があります。しかし、これはもはや新しいデプロイメントの安全な基盤とは言えません。公式のカスタマイズに関するドキュメントでは、このメカニズムは非推奨とされており、2026年9月のv1.12.30リリースノートでは、従来のモジュールおよびカスタマイズAPIが削除されたことが明記されています。

アプリケーションの動作をより詳細に変更したい場合は、プロジェクトのREADMEに記載されているElement Webの現在のモジュールシステムを使用するか、ソースレベルでの制御が本当に必要な場合はフォークを作成してください。フォークは最大限の自由度を提供しますが、Element Webのすべてのアップグレードに対する責任も負うことになります。ロゴ、色、文言、ウェルカムコンテンツ、ホームページの変更のみが必要な場合は、このトレードオフはほとんどメリットがありません。

関連する特殊なケースとして、ソーシャルリンクのプレビュー画像があります。公式の設定ドキュメントによると、この値はではなくog:image静的ファイルに格納されています。そのため、画像を変更する必要がある場合は、実行時のブランディング設定ではなく、ビルド時または静的ファイルのカスタマイズが必要になります。index.htmlconfig.json

検証チェックリスト

• ログインページをプライベートブラウザウィンドウで開き、既存のセッションがない状態で認証ロゴ、背景、フッターリンクが正しく読み込まれることを確認してください。
• アプリがbrandログイン後に意図した値を表示することを確認してください。
• 選択したデフォルトテーマが、以前に外観設定を変更したアカウントだけでなく、新しいブラウザプロファイルにも読み込まれることを確認してください。
• 部屋一覧のテキスト、選択された部屋、補助ラベル、タイムライン、メッセージ作成コントロール、警告、およびフォーカス状態について、読みやすいコントラストになっているか確認してください。
• カスタムのホームページやウェルカムページを使用する場合は、外部ページが利用できない状態でテストを行い、障害発生時の状況を把握してください。
• ブラウザのネットワークパネルを確認し、config.jsonデプロイ後に期待どおりのデータが取得されていることを確認してください。リバースプロキシやCDNのキャッシュが古いことが、正しい設定でも動作しないように見える一般的な原因です。
• Element Webをアップグレードするたびに、カスタムテーマとモジュールAPIの統合を新しいリリースに対して再テストしてから、すべてのユーザーに展開してください。

結論

ほとんどの自己ホスト型Element Webブランディングでは、サポートされている構成レイヤー（brand、、、、および）を使用してください。これによりbranding、 Reactコンポーネントのパッチ適用や従来のカスタマイズフックへの依存よりも、アップグレードがはるかに簡単になります。要件が外観ではなくアプリケーションの動作を真に変更する場合にのみdefault_theme、モジュールAPIまたはメンテナンスされているフォークに移行してください。setting_defaults.custom_themesembedded_pages