Web (JS)

JS/WASM runtime for Rive

This article is out of date! Find the new version here.

Overview

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

Quick Start

See our quick start example that shows how to play a Rive animation on the web.

Getting Started

Follow the steps below on integrating Rive into your web app.

1. Install the dependency

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/canvas@2.9.1"></script>

Find the versions of the runtimes in the "Versions" tab here: https://www.npmjs.com/package/@rive-app/canvas. This will add a global rive object in scope of your web page so that you can access the Rive API's via the rive entry point (i.e. new rive.Rive({}))

Alternatively, you can import our recommended web runtime package via npm/yarn in your project:

npm install @rive-app/canvas

example.js

import * as rive from "@rive-app/canvas";

// Or import just the bits you need
// import { Rive } from "@rive-app/canvas";

Not using Rive Text in your Rive Graphic? Consider using @rive-app/canvas-lite which is a smaller package variant

Want to try out the new Rive Renderer? Take a look at @rive-app/webgl2, which is a preview for the Rive Renderer and WebGL2

If you need more details and options for a web runtime, check out the installation section in the README docs.

2. Create a canvas

Create a canvas element where you want the Rive file to display in your HTML:

<canvas id="canvas" width="500" height="500"></canvas>

3. Create a Rive instance

Create a new instance of a Rive object, providing the following properties:

src - A string of the URL where the .riv file is hosted (like in the example below), or the path to the public asset .riv file (see more in rive parameters for details on how to use this property)
stateMachines - A string of the state machine name you want to play
canvas - The canvas element on which you want the animation to render
autoplay - Boolean for whether you want the default animation to play

<script>
    const r = new rive.Rive({
        src: "https://cdn.rive.app/animations/vehicles.riv",
        // OR the path to a discoverable and public Rive asset
        // src: '/public/example.riv',
        canvas: document.getElementById("canvas"),
        autoplay: true,
        stateMachines: "bumpy",
        onLoad: () => {
          r.resizeDrawingSurfaceToCanvas();
        },
    });
</script>

Complete example

Putting this all together, 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/canvas@2.7.0"></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>

Try it out on your own: Check out this CodeSandbox for a small setup to test your own Rive files!

Loading in Rive files

You can choose to load Rive files in the following ways:

Hosted URL - The string of the URL where the .riv file is hosted. Set this to the src attribute when instantiating a Rive object
Static assets in the bundle - String of a path to a publicly accessible .riv asset in your web project. Treat .riv files 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 src attribute, use the buffer attribute to load in an ArrayBuffer when fetching a file. This is useful if you are re-using a Rive file across multiple Rive instances and want to load it just once. See an example here

See more in the rive parameters src property for further details.

4. Clean up Rive

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:

UI with Rive Animations is no longer necessary (i.e. a modal with Rive graphics is closed)
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();

Resources

Github: https://github.com/rive-app/rive-wasm Examples:

Basic gallery app: https://github.com/rive-app/rive-wasm/tree/master/js/examples/_frameworks/parcel_example_canvas
Tracking mouse cursor: https://codesandbox.io/s/mouse-tracking-on-viewport-gxn16i
Simple skinning: https://codesandbox.io/s/rive-sm-workshop-demo-bare-demo2-ivv1pj
Connecting to page scroll: https://codesandbox.io/s/rive-scroll-example-9llgpp
Playing state machine only when scrolled into the user's viewport: https://codesandbox.io/s/play-rive-when-scrolled-into-view-szxz9c

Last updated 9 months ago