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

About the developer

740 Stars 518 Forks Apache License 2.0 39.2K Commits 154 Opened issues


Matrix SDK for React Javascript

Services available


Need anything else?

Contributors list


This is a react-based SDK for inserting a Matrix chat/voip client into a web page.

This package provides the React components needed to build a Matrix web client using React. It is not useable in isolation, and instead must be used from a 'skin'. A skin provides: * Customised implementations of presentation components. * Custom CSS * The containing application * Zero or more 'modules' containing non-UI functionality

As of Aug 2018, the only skin that exists is

; it and

should effectively be considered as a single project (for instance, matrix-react-sdk bugs are currently filed against vector-im/element-web rather than this project).

Translation Status

Translation status

Developer Guide

Platform Targets: * Chrome, Firefox and Safari. * WebRTC features (VoIP and Video calling) are only available in Chrome & Firefox. * Mobile Web is not currently a target platform - instead please use the native iOS ( and Android ( SDKs.

All code lands on the

branch -
is only used for stable releases. Please file PRs against

Please follow the standard Matrix contributor's guide:

Please follow the Matrix JS/React code style as per:

Code should be committed as follows: * All new components: * Element-specific components: * In practice,

is still evolving so fast that the maintenance burden of customising and overriding these components for Element can seriously impede development. So right now, there should be very few (if any) customisations for Element. * CSS: * Theme specific CSS & resources:

React components in matrix-react-sdk come in two different flavours: 'structures' and 'views'. Structures are stateful components which handle the more complicated business logic of the app, delegating their actual presentation rendering to stateless 'view' components. For instance, the RoomView component that orchestrates the act of visualising the contents of a given Matrix chat room tracks lots of state for its child components which it passes into them for visual rendering via props.

Good separation between the components is maintained by adopting various best practices that anyone working with the SDK needs to be be aware of and uphold:

  • Components are named with upper camel case (e.g. views/rooms/EventTile.js)

  • They are organised in a typically two-level hierarchy - first whether the component is a view or a structure, and then a broad functional grouping (e.g. 'rooms' here)

  • After creating a new component you must run

    yarn reskindex
    to regenerate the
    for the SDK (used in future for skinning) <!-- TODO: Remove this once this approach to skinning is replaced -->
  • The view's CSS file MUST have the same name (e.g. view/rooms/MessageTile.css). CSS for matrix-react-sdk currently resides in

  • Per-view CSS is optional - it could choose to inherit all its styling from the context of the rest of the app, although this is unusual for any but

    • Theme specific CSS & resources: structural components (lacking presentation logic) and the simplest view components.
  • The view MUST only refer to the CSS rules defined in its own CSS file. 'Stealing' styling information from other components (including parents) is not cool, as it breaks the independence of the components.

  • CSS classes are named with an app-specific name-spacing prefix to try to avoid CSS collisions. The base skin shipped by with the matrix-react-sdk uses the naming prefix "mx". A company called Yoyodyne Inc might use a prefix like "yy" for its app-specific classes.

  • CSS classes use upper camel case when they describe React components - e.g. .mx_MessageTile is the selector for the CSS applied to a MessageTile view.

  • CSS classes for DOM elements within a view which aren't components are named by appending a lower camel case identifier to the view's class name - e.g. .mxMessageTilerandomDiv is how you'd name the class of an arbitrary div within the MessageTile view.

  • We deliberately use vanilla CSS 3.0 to avoid adding any more magic dependencies into the mix than we already have. App developers are welcome to use whatever floats their boat however. In future we'll start using css-next to pull in features like CSS variable support.

  • The CSS for a component can override the rules for child components. For instance, .mxRoomList .mxRoomTile {} would be the selector to override styles of RoomTiles when viewed in the context of a RoomList view. Overrides must be scoped to the View's CSS class - i.e. don't just define .mxRoomTile {} in RoomList.css - only RoomTile.css is allowed to define its own CSS. Instead, say .mxRoomList .mx_RoomTile {} to scope the override only to the context of RoomList views. N.B. overrides should be relatively rare as in general CSS inheritance should be enough.

  • Components should render only within the bounding box of their outermost DOM element. Page-absolute positioning and negative CSS margins and similar are generally not cool and stop the component from being reused easily in different places.


followed the Atomic design pattern as per to try to encourage a modular architecture. However, we found that the grouping of components into atoms/molecules/organisms made them harder to find relative to a functional split, and didn't emphasise the distinction between 'structural' and 'view' components, so we backed away from it.

Github Issues

All issues should be filed under for now.


Ensure you have the latest LTS version of Node.js installed.


instead of
is recommended. Please see the Yarn 1 install guide if you do not have it already. This project has not yet been migrated to Yarn 2, so please ensure
yarn --version
shows a version from the 1.x series.

depends on
. To make use of changes in the latter and to ensure tests run against the develop branch of
, you should set up
git clone
cd matrix-js-sdk
git checkout develop
yarn link
yarn install

Then check out

and pull in dependencies:
git clone
cd matrix-react-sdk
git checkout develop
yarn link matrix-js-sdk
yarn install

Generate the component-index.js file.

yarn reskindex

See the help for

yarn link
for more details about this.

Running tests

Ensure you've followed the above development instructions and then:

yarn test

End-to-End tests

Make sure you've got your Element development server running (by doing

yarn start
in element-web), and then in this project, run
yarn run e2etests
. See
for more information.

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.