Convert Figma logo to code with AI

matrix-org logomatrix-react-sdk

Matrix SDK for React Javascript

1,104
834
1,104
78
View on GitHubView on NPM

Top Related Projects

element-hq's avatar

element-web

11,133

A glossy Matrix collaboration client for the web.

syphon-org's avatar

syphon

1,036

⚗️ a privacy centric matrix client

mattermost's avatar

mattermost-webapp

2,289

Archived web app of Mattermost. Moved to the monorepo: https://github.com/mattermost/mattermost

zulip's avatar

zulip

21,350

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

element-hq's avatar

element-android

3,312

A Matrix collaboration client for Android.

Quick Overview

Matrix React SDK is a React-based SDK for building Matrix clients. It provides a set of reusable components and utilities to create custom Matrix chat applications, offering a high level of customization and integration with the Matrix protocol.

Pros

  • Extensive set of pre-built React components for Matrix functionality
  • Highly customizable and extensible
  • Active development and community support
  • Seamless integration with the Matrix protocol

Cons

  • Steep learning curve for developers new to Matrix
  • Large codebase can be overwhelming for small projects
  • Some components may require additional styling for optimal UI/UX
  • Documentation could be more comprehensive for certain advanced features

Code Examples

  1. Creating a simple Matrix client:
import React from 'react';
import { MatrixClient, createClient } from 'matrix-js-sdk';
import { MatrixClientPeg } from 'matrix-react-sdk';

const client = createClient({
    baseUrl: 'https://matrix.org',
    userId: '@user:matrix.org',
    accessToken: 'your_access_token'
});

MatrixClientPeg.set(client);

function App() {
    return (
        <div>
            {/* Your Matrix client components */}
        </div>
    );
}
  1. Rendering a room list:
import React from 'react';
import { RoomList } from 'matrix-react-sdk/src/components/views/rooms/RoomList';

function RoomListContainer() {
    return (
        <RoomList
            onKeyDown={handleKeyDown}
            resizeNotifier={resizeNotifier}
            onFocus={onFocus}
            onBlur={onBlur}
        />
    );
}
  1. Sending a message:
import React, { useState } from 'react';
import { MatrixClientPeg } from 'matrix-react-sdk';

function MessageSender({ roomId }) {
    const [message, setMessage] = useState('');

    const sendMessage = () => {
        const client = MatrixClientPeg.get();
        client.sendTextMessage(roomId, message);
        setMessage('');
    };

    return (
        <div>
            <input
                type="text"
                value={message}
                onChange={(e) => setMessage(e.target.value)}
            />
            <button onClick={sendMessage}>Send</button>
        </div>
    );
}

Getting Started

  1. Install the SDK:
npm install matrix-react-sdk
  1. Set up a basic Matrix client:
import React from 'react';
import { MatrixClient, createClient } from 'matrix-js-sdk';
import { MatrixClientPeg } from 'matrix-react-sdk';

const client = createClient({
    baseUrl: 'https://matrix.org',
    userId: '@user:matrix.org',
    accessToken: 'your_access_token'
});

MatrixClientPeg.set(client);

function App() {
    return (
        <div>
            {/* Your Matrix client components */}
        </div>
    );
}

export default App;
  1. Start using Matrix React SDK components in your application.

Competitor Comparisons

element-hq logo

element-web

11,133

A glossy Matrix collaboration client for the web.

Pros of element-web

  • More comprehensive web application, offering a full-featured Matrix client
  • Includes additional features like voice/video calls and end-to-end encryption
  • Better suited for end-users looking for a complete Matrix experience

Cons of element-web

  • Larger codebase, potentially more complex to maintain and contribute to
  • May have a steeper learning curve for developers new to the project
  • Less flexible for integration into other applications compared to matrix-react-sdk

Code Comparison

matrix-react-sdk:

import React from 'react';
import { MatrixClient } from 'matrix-js-sdk';

const RoomList = ({ matrixClient }) => {
    // Room list component implementation
};

element-web:

import React from 'react';
import { MatrixClient } from 'matrix-js-sdk';
import { RoomList } from 'matrix-react-sdk';

const ElementApp = ({ matrixClient }) => {
    return (
        <div className="element-app">
            <RoomList matrixClient={matrixClient} />
            {/* Additional Element-specific components */}
        </div>
    );
};

The code comparison shows that element-web builds upon matrix-react-sdk, incorporating its components and adding additional functionality specific to the Element client. While matrix-react-sdk provides reusable React components for Matrix, element-web offers a more complete application structure tailored for end-users.

syphon-org logo

syphon

1,036

⚗️ a privacy centric matrix client

Pros of Syphon

  • Built with Flutter, allowing for cross-platform development and potentially better performance
  • Focuses on privacy and security, with end-to-end encryption as a core feature
  • Cleaner, more modern user interface design

Cons of Syphon

  • Smaller community and less mature codebase compared to Matrix React SDK
  • Limited customization options for developers
  • Fewer integrations with third-party services

Code Comparison

Matrix React SDK:

export function getHomePageUrl(state: MatrixState): string {
    const homeServer = state.serverConfig?.hsUrl;
    if (!homeServer) {
        return DEFAULT_HOME_PAGE;
    }
    return `${homeServer}/_matrix/client/r0/login`;
}

Syphon:

String getHomePageUrl(MatrixState state) {
  final homeServer = state.serverConfig?.hsUrl;
  if (homeServer == null) {
    return DEFAULT_HOME_PAGE;
  }
  return '$homeServer/_matrix/client/r0/login';
}

The code comparison shows similar functionality implemented in JavaScript (Matrix React SDK) and Dart (Syphon). Both functions retrieve the home page URL based on the server configuration, with minor syntax differences due to the programming languages used.

mattermost logo

mattermost-webapp

2,289

Archived web app of Mattermost. Moved to the monorepo: https://github.com/mattermost/mattermost

Pros of Mattermost-webapp

  • More active development with frequent updates and contributions
  • Extensive documentation and well-organized codebase
  • Strong focus on enterprise features and scalability

Cons of Mattermost-webapp

  • Steeper learning curve due to larger codebase and complex architecture
  • Less flexibility for customization compared to Matrix-react-sdk
  • Heavier resource usage, potentially impacting performance on low-end devices

Code Comparison

Matrix-react-sdk:

export function useEventEmitter<T extends TypedEventEmitter<Events>>(
    eventEmitter: T,
): void {
    useEffect(() => {
        return () => {
            eventEmitter.removeAllListeners();
        };
    }, [eventEmitter]);
}

Mattermost-webapp:

export function useEventListener(
    eventName: string,
    handler: (event: Event) => void,
    element: HTMLElement | Window = window,
) {
    const savedHandler = useRef<(event: Event) => void>();

    useEffect(() => {
        savedHandler.current = handler;
    }, [handler]);

    useEffect(() => {
        const eventListener = (event: Event) => savedHandler.current?.(event);
        element.addEventListener(eventName, eventListener);
        return () => {
            element.removeEventListener(eventName, eventListener);
        };
    }, [eventName, element]);
}

Both repositories implement custom hooks for event handling, but Mattermost-webapp's implementation is more detailed and flexible, allowing for specific event targeting and cleanup.

zulip logo

zulip

21,350

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

Pros of Zulip

  • More comprehensive project scope, including both frontend and backend
  • Stronger focus on threaded conversations and topic-based organization
  • Extensive documentation and well-defined contribution guidelines

Cons of Zulip

  • Steeper learning curve due to its unique conversation model
  • Less flexibility for customization compared to Matrix's decentralized approach
  • Potentially more resource-intensive to self-host

Code Comparison

Matrix-React-SDK (JavaScript/React):

export function getHomePageUrl(state: MatrixClientPeg.MatrixClient): string {
    const homePageSetting = SettingsStore.getValue("home_page_setting");
    if (homePageSetting === "home_page_custom") {
        return SettingsStore.getValue("home_page_custom_url");
    }
    return getDefaultHomePageUrl(state);
}

Zulip (Python/Django):

def get_default_streams_for_realm(realm):
    return Stream.objects.filter(realm=realm, deactivated=False, invite_only=False,
                                 history_public_to_subscribers=True)

def get_default_subs(user_profile):
    # Start out with the same as the default streams
    return get_default_streams_for_realm(user_profile.realm)

Both repositories showcase clean, well-organized code with clear function naming and structure. Matrix-React-SDK focuses on frontend React components, while Zulip's backend code demonstrates its Django-based architecture.

element-hq logo

element-android

3,312

A Matrix collaboration client for Android.

Pros of Element Android

  • Native Android performance and integration
  • Better offline functionality and push notifications
  • Utilizes Android-specific features and UI patterns

Cons of Element Android

  • Limited to Android platform, reducing cross-platform development efficiency
  • Potentially slower feature parity with web/desktop versions
  • Requires separate codebase maintenance from web/desktop versions

Code Comparison

Matrix React SDK (JavaScript):

export function getDisplayAliasForRoom(room: Room): string | null {
    return room.getCanonicalAlias() || room.getAltAliases()[0] || null;
}

Element Android (Kotlin):

fun getDisplayAliasForRoom(room: Room): String? {
    return room.canonicalAlias ?: room.altAliases.firstOrNull()
}

The code snippets show similar functionality for getting a room's display alias, but implemented in their respective languages and frameworks. The Matrix React SDK uses JavaScript with a more verbose syntax, while Element Android uses Kotlin with a more concise approach, leveraging Kotlin's null-safety features and extension functions.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

npm Tests Playwright Static Analysis Localazy Quality Gate Status Coverage Vulnerabilities Bugs

matrix-react-sdk

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 vector-im/element-web; it and matrix-org/matrix-react-sdk 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).

Developer Guide

Platform Targets:

All code lands on the develop branch - master is only used for stable releases. Please file PRs against develop!!

We use the same contribution guide as Element. Check it out here: https://github.com/vector-im/element-web/blob/develop/CONTRIBUTING.md

Our code style is also the same as Element's: https://github.com/vector-im/element-web/blob/develop/code_style.md

Code should be committed as follows:

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 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)

  • The view's CSS file MUST have the same name (e.g. view/rooms/MessageTile.css). CSS for matrix-react-sdk currently resides in https://github.com/matrix-org/matrix-react-sdk/tree/master/res/css.

  • 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: https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes 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 Matrix.org 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. .mx_MessageTile_randomDiv 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 .mx_RoomTile {} 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 .mx_RoomTile {} in RoomList.css - only RoomTile.css is allowed to define its own CSS. Instead, say .mx_RoomList .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.

Originally matrix-react-sdk followed the Atomic design pattern as per http://patternlab.io 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 https://github.com/vector-im/element-web/issues for now.

Development

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

Using yarn instead of npm 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.

matrix-react-sdk depends on matrix-js-sdk. To make use of changes in the latter and to ensure tests run against the develop branch of matrix-js-sdk, you should set up matrix-js-sdk:

git clone https://github.com/matrix-org/matrix-js-sdk
cd matrix-js-sdk
git checkout develop
yarn link
yarn install

Then check out matrix-react-sdk and pull in dependencies:

git clone https://github.com/matrix-org/matrix-react-sdk
cd matrix-react-sdk
git checkout develop
yarn link matrix-js-sdk
yarn install

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

Running lint

To check your code complies with the project style, ensure you've followed the above development instructions and then:

yarn lint

Dependency problems

If you see errors (particularly "Cannot find module") running the lint or test commands, and yarn install doesn't fix them, it may be because yarn is not fetching git dependencies eagerly enough.

Try running this:

yarn cache clean && yarn install --force

Now the yarn commands should work as normal.

End-to-End tests

We use Playwright and Element Web for end-to-end tests. See docs/playwright.md for more information.

NPM DownloadsLast 30 Days