@matrix-widget-toolkit/mui

This package provides a Mui theme that fits to the default Element theme. It provides:

• Themes that match Element Web (the only Matrix Client that supports the matrix-widget-api right now)
• A light, dark, and high-contract mode
• Adjustments to fulfill accessibility standards

Usage

Install it with:

1yarn add @matrix-widget-toolkit/mui @mui/material

Providing the Widget API to components

Now you can use it in your application:

1import { WidgetApiImpl } from '@matrix-widget-toolkit/api';
2import {
3  MuiThemeProvider,
4  MuiWidgetApiProvider,
5} from '@matrix-widget-toolkit/mui';
6import { Button } from '@mui/material';
7
8// Initiate the widget API on startup. The Client will initiate
9// the connection with `capabilities` and we need to make sure
10// that the message doesn't get lost while we are initiating React.
11const widgetApiPromise = WidgetApiImpl.create();
12
13function App() {
14  return (
15    <MuiThemeProvider>
16      <MuiWidgetApiProvider widgetApiPromise={widgetApiPromise}>
17        <Button>A styled button</Button>
18      </MuiWidgetApiProvider>
19    </MuiThemeProvider>
20  );
21}
22
23export default App;

Setup i18n

The matrix-widget-toolkit uses i18next to provide translations for messages. To make it work in your widget you have to initialize it on your end. See the i18next getting started documentation. This package provides a WidgetToolkitI18nBackend containing the translation data. You can use the ChainedBackend plugin to load translation data for the matrix-widget-toolkit together the translation data for the widget itself. The package provides a WidgetApiLanguageDetector that detects the language from the widget parameters with the i18next-browser-languagedetector plugin. For more details, see the implementation in the example widget.

Requesting capabilities on demand

You can hide child components till the user has approved all required capabilities:

1import { MuiCapabilitiesGuard } from '@matrix-widget-toolkit/mui';
2import { EventDirection, WidgetEventCapability } from 'matrix-widget-api';
3
4<MuiCapabilitiesGuard
5  capabilities={[
6    WidgetEventCapability.forStateEvent(
7      EventDirection.Receive,
8      STATE_EVENT_ROOM_NAME,
9    ),
10  ]}
11>
12  /* Children are only displayed once the user has approved all capabilities. */
13</MuiCapabilitiesGuard>;

Customization

You can override the light primary color by setting the REACT_APP_LIGHT_PRIMARY_COLOR environment variable.

You can override the dark primary color by setting the REACT_APP_DARK_PRIMARY_COLOR environment variable.

Warning Choosing a different primary color might result in not meeting contrast requirements for accessability.

You can force the high contrast theme by setting the REACT_APP_FORCE_HIGH_CONTRAST_THEME environment variable.