Need help with riot-web?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

7.3K Stars 1.2K Forks Apache License 2.0 11.2K Commits 5.0K Opened issues


A glossy Matrix collaboration client for the web.

Services available


Need anything else?

Contributors list


Element (formerly known as Vector and Riot) is a Matrix web client built using the Matrix React SDK.

Supported Environments

Element has several tiers of support for different environments:

  • Supported
    • Definition: Issues actively triaged, regressions block the release
    • Last 2 major versions of Chrome, Firefox, Safari, and Edge on desktop OSes
    • Latest release of official Element Desktop app on desktop OSes
    • Desktop OSes means macOS, Windows, and Linux versions for desktop devices that are actively supported by the OS vendor and receive security updates
  • Experimental
    • Definition: Issues accepted, regressions do not block the release
    • Element as an installed PWA via current stable version of Chrome, Firefox, and Safari
    • Mobile web for current stable version of Chrome, Firefox, and Safari on Android, iOS, and iPadOS
  • Not supported
    • Definition: Issues only affecting unsupported environments are closed
    • Everything else

For accessing Element on an Android or iOS device, we currently recommend the native apps element-android and element-ios.

Getting Started

The easiest way to test Element is to just use the hosted copy at The

branch is continuously deployed to for those who like living dangerously.

To host your own copy of Element, the quickest bet is to use a pre-built released version of Element:

  1. Download the latest version from
  2. Untar the tarball on your web server
  3. Move (or symlink) the
    directory to an appropriate name
  4. Configure the correct caching headers in your webserver (see below)
  5. If desired, copy
    and edit it as desired. See the configuration docs for details.
  6. Enter the URL into your browser and log into Element!

Releases are signed using gpg and the OpenPGP standard, and can be checked against the public key located at

Note that for the security of your chats will need to serve Element over HTTPS. Major browsers also do not allow you to use VoIP/video chats over HTTP, as WebRTC is only usable over HTTPS. There are some exceptions like when using localhost, which is considered a secure context and thus allowed.

To install Element as a desktop application, see Running as a desktop app below.

Important Security Notes

Separate domains

We do not recommend running Element from the same domain name as your Matrix homeserver. The reason is the risk of XSS (cross-site-scripting) vulnerabilities that could occur if someone caused Element to load and render malicious user generated content from a Matrix API which then had trusted access to Element (or other apps) due to sharing the same domain.

We have put some coarse mitigations into place to try to protect against this situation, but it's still not good practice to do it in the first place. See for more details.

Configuration best practices

Unless you have special requirements, you will want to add the following to your web server configuration when hosting Element Web:

  • The
    X-Frame-Options: SAMEORIGIN
    header, to prevent Element Web from being framed and protect from clickjacking.
  • The
    frame-ancestors 'none'
    directive to your
    header, as the modern replacement for
    (though both should be included since not all browsers support it yet, see this).
  • The
    X-Content-Type-Options: nosniff
    header, to disable MIME sniffing.
  • The
    X-XSS-Protection: 1; mode=block;
    header, for basic XSS protection in legacy browsers.

If you are using nginx, this would look something like the following:

add_header X-Frame-Options SAMEORIGIN;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Content-Security-Policy "frame-ancestors 'none'";

Note: In case you are already setting a

header elsewhere, you should modify it to include the
directive instead of adding that last line.

Building From Source

Element is a modular webapp built with modern ES6 and uses a Node.js build system. Ensure you have the latest LTS version of Node.js installed.


instead of
is recommended. Please see the Yarn install guide if you do not have it already.
  1. Install or update
    so that your
    is at least v14.x.
  2. Install
    if not present already.
  3. Clone the repo:
    git clone
  4. Switch to the element-web directory:
    cd element-web
  5. Install the prerequisites:
    yarn install
  6. Configure the app by copying
    and modifying it. See the configuration docs for details.
  7. yarn dist
    to build a tarball to deploy. Untaring this file will give a version-specific directory containing all the files that need to go on your web server.

Note that

yarn dist
is not supported on Windows, so Windows users can run
yarn build
, which will build all the necessary files into the
directory. The version of Element will not appear in Settings without using the dist script. You can then mount the
directory on your web server to actually serve up the app, which is entirely static content.

Running as a Desktop app

Element can also be run as a desktop app, wrapped in Electron. You can download a pre-built version from or, if you prefer, build it yourself.

To build it yourself, follow the instructions at

Many thanks to @aviraldg for the initial work on the Electron integration.

Other options for running as a desktop app:

  • points out that you can use nativefier and it just works(tm)
yarn global add nativefier

The configuration docs show how to override the desktop app's default settings if desired.

Running from Docker

The Docker image can be used to serve element-web as a web server. The easiest way to use it is to use the prebuilt image:

docker run -p 80:80 vectorim/element-web

To supply your own custom

, map a volume to
. For example, if your custom config was located at
then your Docker command would be:
docker run -p 80:80 -v /etc/element-web/config.json:/app/config.json vectorim/element-web

To build the image yourself:

git clone element-web
cd element-web
git checkout master
docker build .

If you're building a custom branch, or want to use the develop branch, check out the appropriate element-web branch and then run:

docker build -t \
    --build-arg USE_CUSTOM_SDKS=true \
    --build-arg REACT_SDK_REPO="" \
    --build-arg REACT_SDK_BRANCH="develop" \
    --build-arg JS_SDK_REPO="" \
    --build-arg JS_SDK_BRANCH="develop" \

Running in Kubernetes

The provided element-web docker image can also be run from within a Kubernetes cluster. See the Kubernetes example for more details.


Element supports a variety of settings to configure default servers, behaviour, themes, etc. See the configuration docs for more details.

Labs Features

Some features of Element may be enabled by flags in the

section of the settings. Some of these features are described in

Caching requirements

Element requires the following URLs not to be cached, when/if you are serving Element from your own webserver:


We also recommend that you force browsers to re-validate any cached copy of Element on page load by configuring your webserver to return

Cache-Control: no-cache
. This ensures the browser will fetch a new version of Element on the next page load after it's been deployed. Note that this is already configured for you in the nginx config of our Dockerfile.


Before attempting to develop on Element you must read the developer guide for

, which also defines the design, architecture and style for Element too.

Before starting work on a feature, it's best to ensure your plan aligns well with our vision for Element. Please chat with the team in before you start so we can ensure it's something we'd be willing to merge.

You should also familiarise yourself with the "Here be Dragons" guide to the tame & not-so-tame dragons (gotchas) which exist in the codebase.

The idea of Element is to be a relatively lightweight "skin" of customisations on top of the underlying

provides both the higher and lower level React components useful for building Matrix communication apps using React.

After creating a new component you must run

yarn reskindex
to regenerate the
for the app (used in future for skinning).

Please note that Element is intended to run correctly without access to the public internet. So please don't depend on resources (JS libs, CSS, images, fonts) hosted by external CDNs or servers but instead please package all dependencies into Element itself.

CSS hot-reload is available as an opt-in development feature. You can enable it by defining a

environment variable, in a
file in the root of the repository. See
for documentation and an example.

Setting up a dev environment

Much of the functionality in Element is actually in the

modules. It is possible to set these up in a way that makes it easy to track the
branches in git and to make local changes without having to manually rebuild each time.

First clone and build

git clone
pushd matrix-js-sdk
yarn link
yarn install

Then similarly with

git clone
pushd matrix-react-sdk
yarn link
yarn link matrix-js-sdk
yarn install

Finally, build and start Element itself:

git clone
cd element-web
yarn link matrix-js-sdk
yarn link matrix-react-sdk
yarn install
yarn reskindex
yarn start

Wait a few seconds for the initial build to finish; you should see something like:

[element-js]  [webpack.Progress] 100%
[element-js] ℹ 「wdm」:    1840 modules
[element-js] ℹ 「wdm」: Compiled successfully.

Remember, the command will not terminate since it runs the web server and rebuilds source files when they change. This development server also disables caching, so do NOT use it in production.

Configure the app by copying

and modifying it. See the configuration docs for details.

Open in your browser to see your newly built Element.

Note: The build script uses inotify by default on Linux to monitor directories for changes. If the inotify limits are too low your build will fail silently or with

Error: EMFILE: too many open files
. To avoid these issues, we recommend a watch limit of at least
and instance limit around

You may be interested in issues #15750 and #15774 for further details.

To set a new inotify watch and instance limit, execute:

sudo sysctl fs.inotify.max_user_watches=131072
sudo sysctl fs.inotify.max_user_instances=512
sudo sysctl -p

If you wish, you can make the new limits permanent, by executing:

echo fs.inotify.max_user_watches=131072 | sudo tee -a /etc/sysctl.conf
echo fs.inotify.max_user_instances=512 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

When you make changes to

they should be automatically picked up by webpack and built.

If you add or remove any components from the Element skin, you will need to rebuild the skin's index by running,

yarn reskindex

If any of these steps error with,

file table overflow
, you are probably on a mac which has a very low limit on max open files. Run
ulimit -Sn 1024
and try again. You'll need to do this in each new terminal you open before building Element.

Running the tests

There are a number of application-level tests in the

directory; these are designed to run in a browser instance under the control of karma. To run them:
  • Make sure you have Chrome installed (a recent version, like 59)
  • Make sure you have
    installed and built, as above
  • yarn test

The above will run the tests under Chrome in a


You can also tell karma to run the tests in a loop (every time the source changes), in an instance of Chrome on your desktop, with

. This also gives you the option of running the tests in 'debug' mode, which is useful for stepping through the tests in the developer tools.

End-to-End tests

See matrix-react-sdk how to run the end-to-end tests.


To add a new translation, head to the translating doc.

For a developer guide, see the translating dev doc.


Triaging issues

Issues are triaged by community members and the Web App Team, following the triage process.

We use issue labels to sort all incoming issues.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.