document custom home view (#21066)

Co-authored-by: Travis Ralston <>
Johannes Krude 3 months ago committed by GitHub
parent 41f05541ed
commit 97fb7f0235
No known key found for this signature in database
  1. 2
  2. 65

@ -193,7 +193,7 @@ Starting with `branding`, the following subproperties are available:
`welcome.html` that ships with Element will be used instead.
2. `home_url`: A URL to an HTML page to show within the app as the "home" page. When the app doesn't have a room/screen to
show the user, it will use the home page instead. The home page is additionally accessible from the user menu. By default,
no home page is set and therefore a hardcoded landing screen is used.
no home page is set and therefore a hardcoded landing screen is used. More documentation and examples are [here](./
3. `login_for_welcome`: When `true` (default `false`), the app will use the login form as a welcome page instead of the welcome
page itself. This disables use of `welcome_url` and all welcome page functionality.

@ -0,0 +1,65 @@
# Custom Home Page
The home page is shown whenever the user is logged in, but no room is selected.
A custom `home.html` replacing the default home page can be configured either in `.well-known/matrix/client` or `config.json`.
Such a custom home page can be used to communicate helpful information and important rules to the users.
## Configuration
To provide a custom home page for all element-web/desktop users of a homeserver, include the following in `.well-known/matrix/client`:
"io.element.embedded_pages": {
"home_url": ""
The home page can be overridden in `config.json` to provide all users of an element-web installation with the same experience:
"embeddedPages": {
"homeUrl": ""
## `home.html` Example
The following is a simple example for a custom `home.html`:
<style type="text/css">
.tos {
width: auto;
color: black;
background : #ffcccb;
font-weight: bold;
<h1>The Matrix Server</h1>
<div class="tos">
<p>Behave appropriately.</p>
<h2>Start Chatting</h2>
<li><a href="#/dm">Send a Direct Message</a></li>
<li><a href="#/directory">Explore Public Rooms</a></li>
<li><a href="#/new">Create a Group Chat</a></li>
When choosing colors, be aware that the home page may be displayed in either light or dark mode.
It may be needed to set CORS headers for the `home.html` to enable element-desktop to fetch it, with e.g., the following nginx config:
add_header Access-Control-Allow-Origin *;