Skip to content

armgit / core

Public Imported from GitHub
0

100% open-source IoT Platform - Integrate your devices, add intelligence, build custom apps

UI: add Rive renderer component (#2666)

Martin Peetersbe10d9b7ec03
diff --git a/ui/app/storybook/docs/components/or-rive-renderer.mdx b/ui/app/storybook/docs/components/or-rive-renderer.mdx
new file mode 100644
index 000000000..6dc8f1ec6
--- /dev/null
+++ b/ui/app/storybook/docs/components/or-rive-renderer.mdx
@@ -0,0 +1,27 @@
+{/*
+ * Copyright 2026, OpenRemote Inc.
+ *
+ * See the CONTRIBUTORS.txt file in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+*/}
+
+import { Meta } from '@storybook/addon-docs/blocks';
+import * as ComponentStory from "../../../../component/or-rive-renderer/stories/or-rive-renderer.stories"; // stories need relative imports
+import {ComponentDocs} from "../../util/componentdocs.mdx";
+
+<Meta title="Components/Rive Renderer" />
+
+<ComponentDocs story={ComponentStory} options={{displayName: "Rive Renderer"}} elementsjson={ComponentStory.customElements} />
diff --git a/ui/app/storybook/rsbuild.config.ts b/ui/app/storybook/rsbuild.config.ts
index 8b0547a0c..f697539c5 100644
--- a/ui/app/storybook/rsbuild.config.ts
+++ b/ui/app/storybook/rsbuild.config.ts
@@ -44,6 +44,7 @@ export default defineConfig({
"@openremote/or-icon": "../../component/or-icon/src",
"@openremote/or-map": "../../component/or-map/src",
"@openremote/or-mwc-components": "../../component/or-mwc-components/src",
+ "@openremote/or-rive-renderer": "../../component/or-rive-renderer/src",
"@openremote/or-scheduler": "../../component/or-scheduler/src",
"@openremote/or-translate": "../../component/or-translate/src",
"@openremote/or-tree-menu": "../../component/or-tree-menu/src",
@@ -59,6 +60,7 @@ export default defineConfig({
},
rspack: (config, { addRules }) => {
addRules([{test: /(maplibre|@material|gridstack|@mdi).*\.css$/, type: "asset/source"}]); // Add rule to treat external CSS imports as raw strings.
+ addRules([{test: /\.wasm$/, type: "asset/resource"}]);
return config;
}
}
diff --git a/ui/app/storybook/util/componentdocs.mdx b/ui/app/storybook/util/componentdocs.mdx
index f23cf8a94..9da48bc0b 100644
--- a/ui/app/storybook/util/componentdocs.mdx
+++ b/ui/app/storybook/util/componentdocs.mdx
@@ -50,7 +50,7 @@ export const ComponentDocs = (props) => {
{/* Description of the component */}
{story.default?.parameters?.docs?.description || customElements.description
- ? <p>{story.default?.parameters?.docs?.description ?? customElements.description}</p>
+ ? <Markdown>{story.default?.parameters?.docs?.description ?? customElements.description}</Markdown>
: <i>Could not find description of the story. Please place a comment above the TypeScript class of the component.</i>
}
diff --git a/ui/component/or-rive-renderer/.npmignore b/ui/component/or-rive-renderer/.npmignore
new file mode 100644
index 000000000..abed2c8ed
--- /dev/null
+++ b/ui/component/or-rive-renderer/.npmignore
@@ -0,0 +1,10 @@
+build/
+build.gradle
+test/
+src/
+webpack.config.js
+rspack.config.js
+playwright.config.ts
+tsconfig.json
+dist/*.map
+*.tsbuildinfo
diff --git a/ui/component/or-rive-renderer/README.md b/ui/component/or-rive-renderer/README.md
new file mode 100644
index 000000000..175ad0fe2
--- /dev/null
+++ b/ui/component/or-rive-renderer/README.md
@@ -0,0 +1,21 @@
+# @openremote/or-rive-renderer
+[![NPM Version][npm-image]][npm-url]
+
+Package containing a Web Component, built with [Lit](https://lit.dev), for displaying `.riv` files from the [Rive](https://rive.app) ecosystem.
+
+## Install
+```bash
+npm i @openremote/or-rive-renderer
+yarn add @openremote/or-rive-renderer
+```
+
+## Example usage
+```html
+<or-rive-renderer url="animations/my-animation.riv"></or-rive-renderer>
+```
+
+## License
+[GNU AGPL](https://www.gnu.org/licenses/agpl-3.0.en.html)
+
+[npm-image]: https://img.shields.io/npm/v/@openremote/or-rive-renderer.svg
+[npm-url]: https://npmjs.org/package/@openremote/or-rive-renderer
diff --git a/ui/component/or-rive-renderer/build.gradle b/ui/component/or-rive-renderer/build.gradle
new file mode 100644
index 000000000..9a12902bb
--- /dev/null
+++ b/ui/component/or-rive-renderer/build.gradle
@@ -0,0 +1,31 @@
+tasks.register('clean') {
+ doLast {
+ delete "dist"
+ delete "lib"
+ delete "tsconfig.tsbuildinfo"
+ }
+}
+
+tasks.register('npmAnalyze', Exec) {
+ mustRunAfter npmClean
+ dependsOn getYarnInstallTask()
+ commandLine npmCommand("yarn"), "run", "analyze"
+}
+
+tasks.register('installDist') {
+ dependsOn npmAnalyze
+}
+
+tasks.register('prepareUi') {
+ dependsOn clean, npmAnalyze, npmPrepare
+}
+
+tasks.register('publishUi') {
+ dependsOn clean, npmPublish
+}
+
+tasks.register('npmBuild', Exec) {
+ mustRunAfter npmClean
+ dependsOn getYarnInstallTask()
+ commandLine npmCommand("yarn"), "run", "build"
+}
diff --git a/ui/component/or-rive-renderer/package.json b/ui/component/or-rive-renderer/package.json
new file mode 100644
index 000000000..a2fecc317
--- /dev/null
+++ b/ui/component/or-rive-renderer/package.json
@@ -0,0 +1,31 @@
+{
+ "name": "@openremote/or-rive-renderer",
+ "version": "1.14.0-snapshot",
+ "description": "A web component for displaying Rive animations using WebGL",
+ "customElements": "custom-elements.json",
+ "main": "dist/umd/index.bundle.js",
+ "module": "lib/index.js",
+ "exports": {
+ ".": "./lib/index.js",
+ "./*": "./lib/*.js"
+ },
+ "types": "lib/index.d.ts",
+ "scripts": {
+ "clean": "npx tsc -b --clean && npx shx rm -rf dist lib",
+ "analyze": "npx cem analyze --config ../custom-elements-manifest.config.mjs",
+ "build": "npx tsc -b",
+ "test": "npx tsc -b && npx playwright test",
+ "prepack": "npx rspack"
+ },
+ "author": "OpenRemote",
+ "repository": "https://github.com/openremote/openremote",
+ "license": "AGPL-3.0-or-later",
+ "dependencies": {
+ "@rive-app/webgl2": "^2.35.4",
+ "lit": "^3.3.1",
+ "lodash.debounce": "^4.0.8"
+ },
+ "publishConfig": {
+ "access": "public"
+ }
+}
diff --git a/ui/component/or-rive-renderer/rspack.config.js b/ui/component/or-rive-renderer/rspack.config.js
new file mode 100644
index 000000000..cd4bc1144
--- /dev/null
+++ b/ui/component/or-rive-renderer/rspack.config.js
@@ -0,0 +1,13 @@
+const util = require("@openremote/util");
+
+bundles = {
+ "index": {
+ excludeOr: true
+ },
+ "index.bundle": {
+ excludeOr: true,
+ },
+ "index.orbundle": undefined
+};
+
+module.exports = util.generateExports(__dirname);
diff --git a/ui/component/or-rive-renderer/src/index.ts b/ui/component/or-rive-renderer/src/index.ts
new file mode 100644
index 000000000..f0b7acab9
--- /dev/null
+++ b/ui/component/or-rive-renderer/src/index.ts
@@ -0,0 +1,177 @@
+/*
+ * Copyright 2026, OpenRemote Inc.
+ *
+ * See the CONTRIBUTORS.txt file in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+import {customElement, property, query} from "lit/decorators.js";
+import {LitElement, PropertyValues, css, html} from "lit";
+import {Rive, RuntimeLoader, ViewModelInstance} from "@rive-app/webgl2";
+import debounce from "lodash.debounce";
+
+// Import WebAssembly required for running Rive
+// @ts-ignore
+import riveWASMResource from "@rive-app/webgl2/rive.wasm";
+
+RuntimeLoader.setWasmUrl(riveWASMResource);
+
+@customElement("or-rive-renderer")
+export class OrRiveRenderer extends LitElement {
+
+ static get styles() {
+ return [css`
+ :host {
+ display: block;
+ position: relative;
+ width: 100%;
+ height: 100%;
+ overflow: hidden;
+ min-height: 2rem; /* Prevent 0-height collapses */
+ }
+ canvas {
+ display: block;
+ position: absolute;
+ top: 0;
+ left: 0;
+ width: 100%;
+ height: 100%;
+ }
+ `];
+ }
+
+ /**
+ * A string representing the URL or path to the public asset .riv file.
+ * For more details, refer to Rive Parameters on how to properly use this property.
+ */
+ @property({type: String})
+ public url?: string;
+
+ /**
+ * The string representing the artboard you want to display.
+ * When not supplied, the default artboard from the .riv file is selected.
+ * Docs: https://rive.app/docs/runtimes/web/artboards
+ */
+ @property({type: String})
+ public artboard?: string;
+
+ /**
+ * A list of strings (`["My State Machine"]`) you wish to display.
+ * Look up the Rive documentation for more info: https://rive.app/docs/runtimes/web/state-machines.
+ * By default, the state machine will autoplay.
+ */
+ @property({type: Array})
+ public stateMachines?: string[];
+
+ @query("canvas")
+ protected _canvas?: HTMLCanvasElement;
+
+ protected _rive?: Rive;
+ protected _resizeObserver?: ResizeObserver;
+ protected _valueQueue: (() => void)[] = [];
+
+ /**
+ * Public function for updating data within the animation using "View Models".
+ * For example, if the animation has a state property named "myValue", you can use this function to update the value to "100".
+ * Full documentation can be found here: https://rive.app/docs/runtimes/web/data-binding
+ * @param name - Name of the state property inside the .riv animation
+ * @param value - Value to set. It will auto-detect the object {@link type}.
+ * @param type - (optional) the value type to set. Currently, the supported types are: string, boolean, number, color and enum. Everything else will be converted to a trigger.
+ */
+ public async setValue(name: string, value?: any, type: string = typeof value): Promise<void> {
+ await this.updateComplete;
+ const func = () => {
+ const vmi = this._rive!.viewModelInstance as ViewModelInstance;
+ console.debug(`Setting ${name} ${type} value of Rive animation ${this.artboard} to`, value);
+ if(type === "string") {
+ vmi.string(name)!.value = value;
+ } else if(type === "boolean") {
+ vmi.boolean(name)!.value = value;
+ } else if(type === "number") {
+ vmi.number(name)!.value = value;
+ } else if(type === "color") {
+ vmi.color(name)!.value = value;
+ } else if(type === "enum") {
+ vmi.enum(name)!.value = value;
+ } else {
+ vmi.trigger(name);
+ }
+ };
+ // If Rive has not been loaded yet, cache the function until it does.
+ if(!this._rive?.viewModelInstance) {
+ this._valueQueue.push(func);
+ return;
+ }
+ func();
+ }
+
+ connectedCallback() {
+ super.connectedCallback();
+ this._resizeObserver = new ResizeObserver(entries => this._onResize(entries));
+ this._resizeObserver.observe(this);
+ }
+
+ disconnectedCallback() {
+ this._resizeObserver?.disconnect();
+ this._onResize.cancel();
+ this._rive?.deleteRiveRenderer();
+ super.disconnectedCallback();
+ }
+
+ updated(changedProps: PropertyValues) {
+ if (!this.url || !this._canvas) {
+ console.warn("Could not render Rive animation; some details were missing");
+ } else {
+ this._rive?.deleteRiveRenderer();
+ console.debug("Loading Rive animation of artboard", this.artboard);
+ this._rive = new Rive({
+ artboard: this.artboard,
+ src: this.url,
+ canvas: this._canvas,
+ autoplay: true,
+ autoBind: true,
+ stateMachines: this.stateMachines,
+ onLoad: () => {
+ this._rive?.resizeDrawingSurfaceToCanvas();
+ if(this._valueQueue) {
+ this._valueQueue.forEach(func => func());
+ this._valueQueue = [];
+ }
+ }
+ });
+ }
+ return super.updated(changedProps);
+ }
+
+ render() {
+ return html`
+ <canvas></canvas>
+ `;
+ }
+
+ /**
+ * Callback function when this web component changes in size.
+ * In this case, it is used for calling a Rive JS function to calibrate using the new canvas size.
+ * @protected
+ */
+ protected _onResize = debounce((entries: ResizeObserverEntry[]) => {
+ if(this._canvas && entries?.length > 0) {
+ this._canvas.width = entries[0].contentRect.width;
+ this._canvas.height = entries[0].contentRect.height;
+ }
+ this._rive?.resizeDrawingSurfaceToCanvas();
+ }, 150);
+
+}
diff --git a/ui/component/or-rive-renderer/stories/or-rive-renderer.stories.ts b/ui/component/or-rive-renderer/stories/or-rive-renderer.stories.ts
new file mode 100644
index 000000000..beb64db20
--- /dev/null
+++ b/ui/component/or-rive-renderer/stories/or-rive-renderer.stories.ts
@@ -0,0 +1,68 @@
+/*
+ * Copyright 2026, OpenRemote Inc.
+ *
+ * See the CONTRIBUTORS.txt file in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+import {setCustomElementsManifest, type Meta, type StoryObj} from "@storybook/web-components";
+import {getORStorybookHelpers} from "../../storybook-utils.js";
+import customElements from "../custom-elements.json" with {type: "json"};
+import packageJson from "../package.json" with {type: "json"};
+import "../src/index";
+import { html } from "lit";
+
+const tagName = "or-rive-renderer";
+type Story = StoryObj;
+setCustomElementsManifest(customElements);
+
+const { events, args, argTypes, template } = getORStorybookHelpers(tagName);
+
+const meta: Meta = {
+ title: "Playground/or-rive-renderer",
+ component: tagName,
+ args: args,
+ argTypes: argTypes,
+ render: storyArgs => template(storyArgs),
+ excludeStories: /^[a-z].*/,
+ parameters: {
+ actions: {
+ handles: events
+ },
+ docs: {
+ subtitle: `<${tagName}>`,
+ description: "A Web Component for displaying `.riv` files from the [Rive](https://rive.app) ecosystem.",
+ story: {
+ height: "370px"
+ }
+ }
+ }
+};
+
+export const Primary: Story = {
+ render: args => html`
+ <style>or-rive-renderer { height: 256px; }</style>
+ ${template(args)}
+ `,
+ args: {
+ url: "https://cdn.rive.app/animations/vehicles.riv"
+ }
+};
+
+export const examples: Story[] = [];
+
+export { customElements, packageJson };
+
+export default meta;
diff --git a/ui/component/or-rive-renderer/tsconfig.json b/ui/component/or-rive-renderer/tsconfig.json
new file mode 100644
index 000000000..dd3861cf9
--- /dev/null
+++ b/ui/component/or-rive-renderer/tsconfig.json
@@ -0,0 +1,10 @@
+{
+ "extends": "../../tsconfig",
+ "compilerOptions": {
+ "outDir": "./lib",
+ "rootDir": "src"
+ },
+ "include": [
+ "./src"
+ ]
+}
diff --git a/ui/util/webpack.util.js b/ui/util/webpack.util.js
index 8b15aa4e7..03e88105e 100644
--- a/ui/util/webpack.util.js
+++ b/ui/util/webpack.util.js
@@ -11,6 +11,10 @@ function getStandardModuleRules() {
test: /(maplibre|@material|gridstack|@mdi).*\.css$/, //output css as strings
type: "asset/source"
},
+ {
+ test: /\.wasm$/,
+ type: "asset/resource"
+ },
{
test: /\.css$/, //
exclude: /(maplibre|@material|gridstack|@mdi).*\.css$/,
@@ -83,6 +87,9 @@ function getAppConfig(mode, isDevServer, dirname, managerUrl, keycloakUrl, port)
"vm": false,
"querystring": require.resolve("querystring-es3")
}
+ },
+ experiments: {
+ asyncWebAssembly: true
}
};
diff --git a/yarn.lock b/yarn.lock
index 957852f49..928801a51 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2165,6 +2165,16 @@ __metadata:
languageName: unknown
linkType: soft
+"@openremote/or-rive-renderer@workspace:ui/component/or-rive-renderer":
+ version: 0.0.0-use.local
+ resolution: "@openremote/or-rive-renderer@workspace:ui/component/or-rive-renderer"
+ dependencies:
+ "@rive-app/webgl2": "npm:^2.35.4"
+ lit: "npm:^3.3.1"
+ lodash.debounce: "npm:^4.0.8"
+ languageName: unknown
+ linkType: soft
+
"@openremote/or-rules@workspace:*, @openremote/or-rules@workspace:ui/component/or-rules":
version: 0.0.0-use.local
resolution: "@openremote/or-rules@workspace:ui/component/or-rules"
@@ -2552,6 +2562,13 @@ __metadata:
languageName: node
linkType: hard
+"@rive-app/webgl2@npm:^2.35.4":
+ version: 2.35.4
+ resolution: "@rive-app/webgl2@npm:2.35.4"
+ checksum: 10c0/df8996510459d3388d027589c8fe628673bc49d550dd850ee5fc2752586706d78ccc7709332e40962f8aa30cd3febb94e51ff564ae35b36816917156476f4f03
+ languageName: node
+ linkType: hard
+
"@rollup/rollup-android-arm-eabi@npm:4.41.0":
version: 4.41.0
resolution: "@rollup/rollup-android-arm-eabi@npm:4.41.0"