Web (JS)
JS/WASM runtime for Rive
This guide documents how to get started using the Web runtime library. Rive runtime libraries are open-source. The source is available in its GitHub repository.
This library has both a high-level JavaScript API (with TypeScript support), as well as a low-level API to load in Web Assembly (WASM) and control the rendering loop yourself. This runtime is great for the following:
- Quickly integrating Rive into all kinds of web applications (i.e Webflow, Wordpress, etc.)
- Providing a base API to build other web-based Rive runtime wrappers (i.e React, Angular, etc.)
- Advanced use cases in controlling a render loop
Follow the steps below for a quick start on integrating Rive into your web app.
Add the following script tag to a web page; we recommend sticking to one version, such as seen below:
<script src="https://unpkg.com/@rive-app/[email protected]"></script>
Find the versions of the runtimes in the "Versions" tab here: https://www.npmjs.com/package/@rive-app/canvas
Alternatively, you can import our recommended web runtime package via npm/yarn in your project:
npm install @rive-app/canvas
// example.js
import rive from "@rive-app/canvas";
If you need more details and options for a web runtime, check out the installation section in the README docs.
Create a canvas element where you want the Rive file to display in your HTML:
<canvas id="canvas" width="500" height="500"></canvas>
Create a new instance of a Rive object, providing the following properties:
src- A string of the URL where the.rivfile is hosted (like in the example below), or the path to the public asset.rivfile (see more in rive parameters for details on how to use this property)stateMachines- A string of the state machine name you want to playcanvas- The canvas element on which you want the animation to renderautoplay- Boolean for whether you want the default animation to play
<script>
new rive.Rive({
src: "https://cdn.rive.app/animations/vehicles.riv",
// Or the path to a public Rive asset
// src: '/public/example.riv',
canvas: document.getElementById("canvas"),
autoplay: true,
stateMachines: "bumpy",
});
</script>
Putting this altogether, you can load an example Rive animation in one HTML file.
Additionally, we'll add an
onLoad callback to the Rive object to use Rive's resizeDrawingSurfaceToCanvas() API to respect the device pixel ratio and prevent a blurry canvas from displaying. In a future release, this may be the default behavior, and you may need to opt-out if you do not want Rive to set your <canvas> width and height properties for you.<html>
<head>
<title>Rive Hello World</title>
</head>
<body>
<canvas id="canvas" width="500" height="500"></canvas>
<script src="https://unpkg.com/@rive-app/[email protected]"></script>
<script>
const r = new rive.Rive({
src: "https://cdn.rive.app/animations/vehicles.riv",
canvas: document.getElementById("canvas"),
autoplay: true,
stateMachines: "bumpy",
onLoad: () => {
r.resizeDrawingSurfaceToCanvas();
},
});
</script>
</body>
</html>
You can choose to load Rive files in the following ways:
- Hosted URL - The string of the URL where the
.rivfile is hosted. Set this to thesrcattribute when instantiating aRiveobject - Static assets in the bundle - String of a path to a publicly accessible
.rivasset in your web project. Treat.rivfiles in the project just as you would any other asset in your bundle, such as images or font files. - Fetching a file - Instead of using the
srcattribute, use thebufferattribute to load in an ArrayBuffer when fetching a file. See an example here
When creating a Rive instance, you need to ensure that it gets cleaned up. This should happen in scenarios where you no longer want to show the Rive canvas, for example, where:
- The user navigates off the page showing Rive animations
- The animation or state machine has completed and will no longer ever be run/shown
Behind the scenes, lower-level CPP objects are created and must be deleted (i.e artboard instances, animation instances, state machine instances, etc.) manually. This helps prevent unwanted memory leaks and keeps your web application lean on resources. Luckily, with this high-level JS API, there is no need to track and manage what was created for deletion, as there is one method call you can make to effectively clean up all the instances created.
When you're ready to clean up Rive, simply call the following API on the Rive instance you created:
const riveInstance = new Rive({...));
...
// When ready to cleanup
riveInstance.cleanup();
Last modified 11d ago