JavaScript/TypeScript API for widgets & web clients to communicate
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-01 14:33:17 +00:00
.github Update actions/checkout action to v5 (#150) 2025-11-05 15:30:17 -05:00
docs Update release docs now that we're out of beta (#70) 2022-08-08 12:27:03 -04:00
examples Apply some code quality suggestions from SonarQube (#144) 2025-11-04 16:44:13 -05:00
src Update LiveKit actions to reflect latest changes to MSC4533 (#169) 2026-10-01 15:55:26 +02:00
test Update LiveKit actions to reflect latest changes to MSC4533 (#169) 2026-10-01 15:55:26 +02:00
.babelrc Add prettier config (#123) 2025-01-27 07:24:18 -05:00
.eslintrc.js Apply some code quality suggestions from SonarQube (#144) 2025-11-04 16:44:13 -05:00
.gitignore Add UPDATE_STATE widget api version (#125) 2025-01-24 09:35:03 +01:00
.node-version Upgrade Node to latest LTS (#149) 2025-11-05 15:26:26 -05:00
.prettierrc.js Add prettier config (#123) 2025-01-27 07:24:18 -05:00
CONTRIBUTING.md remove real name requirement from DCO (#93) 2024-07-31 09:21:15 -04:00
jest.config.ts Upgrade dependencies 2023-04-24 13:07:41 +01:00
LICENSE Initial commit 2020-09-04 13:11:05 -06:00
package.json minor version bump 2026-10-01 14:33:17 +00:00
README.md Add prettier config (#123) 2025-01-27 07:24:18 -05:00
renovate.json Add prettier config (#123) 2025-01-27 07:24:18 -05:00
sonar-project.properties Report coverage into SonarCloud (#82) 2023-04-24 12:50:07 +01:00
tsconfig-dev.json Add prettier config (#123) 2025-01-27 07:24:18 -05:00
tsconfig.json Apply some code quality suggestions from SonarQube (#144) 2025-11-04 16:44:13 -05:00
yarn.lock Update dependency @stylistic/eslint-plugin to v5 (#140) 2026-08-25 10:48:50 +02:00

matrix-widget-api

npm

JavaScript/TypeScript SDK for widgets & clients to communicate.

For help and support, visit #matrix-widgets:matrix.org on Matrix.

Disclaimer: Widgets are not yet in the Matrix spec, so this library may not work with other implementations.

Building

To transpile this project to JavaScript, run:

yarn install
yarn build

Using the API without a bundler

If you're looking to drop the widget-api into a web browser without the use of a bundler, add a script tag similar to the following:

<script src="https://unpkg.com/matrix-widget-api@0.1.0/dist/api.min.js"></script>

Note that the version number may need changing to match the current release.

Once included, the widget-api will be available under mxwidgets. For example, new mxwidgets.WidgetApi(...) to instantiate the WidgetApi class.

Usage for widgets

The general usage for this would be:

const widgetId = null; // if you know the widget ID, supply it.
const api = new WidgetApi(widgetId);

// Before doing anything else, request capabilities:
api.requestCapability(MatrixCapabilities.Screenshots);
api.requestCapabilities(StickerpickerCapabilities);

// Add custom action handlers (if needed)
api.on(`action:${WidgetApiToWidgetAction.UpdateVisibility}`, (ev: CustomEvent<IVisibilityActionRequest>) => {
    ev.preventDefault(); // we're handling it, so stop the widget API from doing something.
    console.log(ev.detail); // custom handling here
    api.transport.reply(ev.detail, <IWidgetApiRequestEmptyData>{});
});
api.on("action:com.example.my_action", (ev: CustomEvent<ICustomActionRequest>) => {
    ev.preventDefault(); // we're handling it, so stop the widget API from doing something.
    console.log(ev.detail); // custom handling here
    api.transport.reply(ev.detail, { custom: "reply" });
});

// Start the messaging
api.start();

// If waitForIframeLoad is false, tell the client that we're good to go
api.sendContentLoaded();

// Later, do something else (if needed)
api.setAlwaysOnScreen(true);
api.transport.send("com.example.my_action", { isExample: true });

For a more complete example, see the examples directory of this repo.

Usage for web clients

This SDK is meant for use in browser-based applications. The concepts may be transferable to other platforms, though currently this SDK is intended to only be used by browsers. In the future it may be possible for this SDK to provide an interface for other platforms.

TODO: Improve this

const driver = new CustomDriver(); // an implementation of WidgetDriver
const api = new ClientWidgetApi(widget, iframe, driver);

// The API is automatically started, so we just have to wait for a ready before doing something
api.on("ready", () => {
    api.updateVisibility(true).then(() => console.log("Widget knows it is visible now"));
    api.transport.send("com.example.my_action", { isExample: true });
});

// Eventually, stop the API handling
api.stop();