{"id":13688651,"url":"https://github.com/matrix-org/matrix-widget-api","last_synced_at":"2025-05-16T13:03:14.807Z","repository":{"id":38002040,"uuid":"292927372","full_name":"matrix-org/matrix-widget-api","owner":"matrix-org","description":"JavaScript/TypeScript API for widgets \u0026 web clients to communicate","archived":false,"fork":false,"pushed_at":"2025-05-05T23:03:07.000Z","size":631,"stargazers_count":71,"open_issues_count":32,"forks_count":19,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-06T00:20:26.506Z","etag":null,"topics":["hacktoberfest","matrix","matrix-widget-api","widgets"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"patreon":"matrixdotorg","liberapay":"matrixdotorg"}},"created_at":"2020-09-04T19:11:03.000Z","updated_at":"2025-05-05T06:14:03.000Z","dependencies_parsed_at":"2024-11-01T06:19:51.588Z","dependency_job_id":"5cbac862-104f-4ea9-9ef9-6391210b275a","html_url":"https://github.com/matrix-org/matrix-widget-api","commit_stats":{"total_commits":149,"total_committers":20,"mean_commits":7.45,"dds":0.4832214765100671,"last_synced_commit":"bbff7c16a4ee7c5b0cc7c117098c659fd94f27ba"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-widget-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-widget-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-widget-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-widget-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/matrix-widget-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535826,"owners_count":22087398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","matrix","matrix-widget-api","widgets"],"created_at":"2024-08-02T15:01:18.759Z","updated_at":"2025-05-16T13:03:14.786Z","avatar_url":"https://github.com/matrix-org.png","language":"TypeScript","funding_links":["https://patreon.com/matrixdotorg","https://liberapay.com/matrixdotorg"],"categories":["TypeScript","Widgets"],"sub_categories":["2016"],"readme":"# matrix-widget-api\n\n![npm](https://img.shields.io/npm/v/matrix-widget-api?style=for-the-badge)\n\nJavaScript/TypeScript SDK for widgets \u0026 clients to communicate.\n\nFor help and support, visit [#matrix-widgets:matrix.org](https://matrix.to/#/#matrix-widgets:matrix.org) on Matrix.\n\n_Disclaimer: Widgets are not yet in the Matrix spec, so this library may not work with other implementations._\n\n## Building\n\nTo transpile this project to JavaScript, run:\n\n```\nyarn install\nyarn build\n```\n\n## Using the API without a bundler\n\nIf you're looking to drop the widget-api into a web browser without the use of a bundler, add a `script`\ntag similar to the following:\n\n```html\n\u003cscript src=\"https://unpkg.com/matrix-widget-api@0.1.0/dist/api.min.js\"\u003e\u003c/script\u003e\n```\n\nNote that the version number may need changing to match the current release.\n\nOnce included, the widget-api will be available under `mxwidgets`. For example, `new mxwidgets.WidgetApi(...)`\nto instantiate the `WidgetApi` class.\n\n## Usage for widgets\n\nThe general usage for this would be:\n\n```typescript\nconst widgetId = null; // if you know the widget ID, supply it.\nconst api = new WidgetApi(widgetId);\n\n// Before doing anything else, request capabilities:\napi.requestCapability(MatrixCapabilities.Screenshots);\napi.requestCapabilities(StickerpickerCapabilities);\n\n// Add custom action handlers (if needed)\napi.on(`action:${WidgetApiToWidgetAction.UpdateVisibility}`, (ev: CustomEvent\u003cIVisibilityActionRequest\u003e) =\u003e {\n    ev.preventDefault(); // we're handling it, so stop the widget API from doing something.\n    console.log(ev.detail); // custom handling here\n    api.transport.reply(ev.detail, \u003cIWidgetApiRequestEmptyData\u003e{});\n});\napi.on(\"action:com.example.my_action\", (ev: CustomEvent\u003cICustomActionRequest\u003e) =\u003e {\n    ev.preventDefault(); // we're handling it, so stop the widget API from doing something.\n    console.log(ev.detail); // custom handling here\n    api.transport.reply(ev.detail, { custom: \"reply\" });\n});\n\n// Start the messaging\napi.start();\n\n// If waitForIframeLoad is false, tell the client that we're good to go\napi.sendContentLoaded();\n\n// Later, do something else (if needed)\napi.setAlwaysOnScreen(true);\napi.transport.send(\"com.example.my_action\", { isExample: true });\n```\n\nFor a more complete example, see the `examples` directory of this repo.\n\n## Usage for web clients\n\nThis SDK is meant for use in browser-based applications. The concepts may be transferable to other platforms,\nthough currently this SDK is intended to only be used by browsers. In the future it may be possible for this\nSDK to provide an interface for other platforms.\n\nTODO: Improve this\n\n```typescript\nconst driver = new CustomDriver(); // an implementation of WidgetDriver\nconst api = new ClientWidgetApi(widget, iframe, driver);\n\n// The API is automatically started, so we just have to wait for a ready before doing something\napi.on(\"ready\", () =\u003e {\n    api.updateVisibility(true).then(() =\u003e console.log(\"Widget knows it is visible now\"));\n    api.transport.send(\"com.example.my_action\", { isExample: true });\n});\n\n// Eventually, stop the API handling\napi.stop();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-widget-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmatrix-widget-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-widget-api/lists"}