Repository files navigation

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

Element has several tiers of support for different environments:

• Supported
  • Definition:
    • Issuesactively triaged, regressionsblock the release
  • Last 2 major versions of Chrome, Firefox, and Edge on desktop OSes
  • Last 2 versions of Safari
  • Latest release of official Element Desktop app on desktop OSes
  • Desktop OSes means macOS, Windows, and Linux versions for desktop devicesthat are actively supported by the OS vendor and receive security updates
• Best effort
  • Definition:
    • Issuesaccepted, regressionsdo not block the release
    • The wider Element Products(including Element Call and the Enterprise Server Suite) do still not officially support these browsers.
    • The element web project and its contributors should keep the client functioning and gracefully degrade where other sibling features (E.g. Element Call) may not function.
  • Last major release of Firefox ESR and Chrome/Edge Extended Stable
• Community Supported
  • Definition:
    • Issuesaccepted, regressionsdo not block the release
    • Community contributions are welcome to support these issues
  • Mobile web for current stable version of Chrome, Firefox, and Safari on Android, iOS, and iPadOS
• Not supported
  • Definition: Issues only affecting unsupported environments areclosed
  • Everything else

The period of support for these tiers should last until the releases specified above, plus 1 app release cycle(2 weeks). In the case of Firefox ESR this is extended further to allow it land in Debian Stable.

For accessing Element on an Android or iOS device, we currently recommend thenative appselement-androidandelement-ios.

The easiest way to test Element is to just use the hosted copy athttps://app.element.io.Thedevelop branch is continuously deployed tohttps://develop.element.iofor those who like living dangerously.

To host your own instance of Element seeInstalling Element Web.

To install Element as a desktop application, seeRunning as a desktop app below.

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

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

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

• TheX-Frame-Options: SAMEORIGIN header, to prevent Element Web from beingframed and protect fromclickjacking.
• Theframe-ancestors 'self' directive to yourContent-Security-Policyheader, as the modern replacement forX-Frame-Options (though both should beincluded since not all browsers support it yet, seethis).
• TheX-Content-Type-Options: nosniff header, todisable MIMEsniffing.
• TheX-XSS-Protection: 1; mode=block; header, for basic XSS protection inlegacy 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 'self'";

For Apache, the configuration looks like:

Header set X-Frame-Options SAMEORIGINHeader set X-Content-Type-Options nosniffHeader set X-XSS-Protection "1; mode=block"Header set Content-Security-Policy "frame-ancestors 'self'"

Note: In case you are already setting aContent-Security-Policy headerelsewhere, you should modify it to include theframe-ancestors directiveinstead of adding that last line.

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.

Usingyarn instead ofnpm is recommended. Please see the Yarninstallguide if you do not have it already.

1. Install or updatenode.js so that yournode is at least the current recommended LTS.
2. Installyarn if not present already.
3. Clone the repo:git clone https://github.com/element-hq/element-web.git.
4. Switch to the element-web directory:cd element-web.
5. Install the prerequisites:yarn install.
   • If you're using thedevelop branch, then it is recommended to set up aproper development environment (seeSetting up a devenvironment below). Alternatively, youcan usehttps://develop.element.io - the continuous integration release ofthe develop branch.
6. Configure the app by copyingconfig.sample.json toconfig.json andmodifying it. See theconfiguration docs for details.
7. yarn dist to build a tarball to deploy. Untaring this file will givea version-specific directory containing all the files that need to go on yourweb server.

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

Element can also be run as a desktop app, wrapped in Electron. You can download apre-built version fromhttps://element.io/get-started or, if you prefer,build it yourself.

To build it yourself, follow the instructions athttps://github.com/element-hq/element-desktop.

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

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

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

Some features of Element may be enabled by flags in theLabs section of the settings.Some of these features are described inlabs.md.

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

/config.*.json/i18n/home/sites/index.html

We also recommend that you force browsers to re-validate any cached copy of Element on page load by configuring yourwebserver to returnCache-Control: no-cache for/. This ensures the browser will fetch a new version of Element onthe next page load after it's been deployed. Note that this is already configured for you in the nginx config of ourDockerfile.

Before attempting to develop on Element youmust read thedeveloper guideformatrix-react-sdk, whichalso defines the design, architecture and style for Element too.

Read theChoosing an issue page for some guidanceabout where to start. Before starting work on a feature, it's best to ensureyour plan aligns well with our vision for Element. Please chat with the team in#element-dev:matrix.org beforeyou start so we can ensure it's something we'd be willing to merge.

You should also familiarise yourself with the"Here be Dragons" guideto 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 ontop of the underlyingmatrix-react-sdk.matrix-react-sdk provides both thehigher and lower level React components useful for building Matrix communicationapps using React.

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

Much of the functionality in Element is actually in thematrix-js-sdk module.It is possible to set these up in a way that makes it easy to track thedevelop branchesin git and to make local changes without having to manually rebuild each time.

First clone and buildmatrix-js-sdk:

git clone https://github.com/matrix-org/matrix-js-sdk.gitpushd matrix-js-sdkyarn linkyarn installpopd

Clone the repo and switch to theelement-web directory:

git clone https://github.com/element-hq/element-web.gitcd element-web

Configure the app by copyingconfig.sample.json toconfig.json andmodifying it. See theconfiguration docs for details.

Finally, build and start Element itself:

yarn link matrix-js-sdkyarn installyarn start

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

[element-js] <s> [webpack.Progress] 100%[element-js][element-js] ℹ ｢wdm｣:    1840 modules[element-js] ℹ ｢wdm｣: Compiled successfully.

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

Openhttp://127.0.0.1:8080/ in your browser to see your newly built Element.

Note: The build script uses inotify by default on Linux to monitor directoriesfor changes. If the inotify limits are too low your build will fail silently or withError: EMFILE: too many open files. To avoid these issues, we recommend a watch limitof at least128M and instance limit around512.

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=131072sudo sysctl fs.inotify.max_user_instances=512sudo 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.confecho fs.inotify.max_user_instances=512 | sudo tee -a /etc/sysctl.confsudo sysctl -p

When you make changes tomatrix-js-sdk they should be automatically picked up by webpack and built.

If any of these steps error with,file table overflow, you are probably on a macwhich has a very low limit on max open files. Runulimit -Sn 1024 and try again.You'll need to do this in each new terminal you open before building Element.

There are a number of application-level tests in thetests directory; theseare designed to run with Jest and JSDOM. To run them

yarn test

Seematrix-react-sdk for how to run the end-to-end tests.

To add a new translation, head to thetranslating doc.

For a developer guide, see thetranslating dev doc.

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

We useissue labels to sort all incoming issues.

Copyright (c) 2014-2017 OpenMarket LtdCopyright (c) 2017 Vector Creations LtdCopyright (c) 2017-2025 New Vector Ltd

This software is multi licensed by New Vector Ltd (Element). It can be used either:

(1) for free under the terms of the GNU Affero General Public License (as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version); OR

(2) for free under the terms of the GNU General Public License (as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version); OR

(3) under the terms of a paid-for Element Commercial License agreement between you and Element (the terms of which may vary depending on what you and Element have agreed to).Unless required by applicable law or agreed to in writing, software distributed under the Licenses is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licenses for the specific language governing permissions and limitations under the Licenses.