​
Overview

This guide documents how to get started using the Rive web runtime library. The runtime is open source and available in this GitHub repository. This library has a high-level JavaScript API (with TypeScript support) and a low-level API to load in Web Assembly (WASM) and control the rendering loop yourself. This runtime allows you to:

  • Quickly integrate Rive into all web applications (Webflow, WordPress, etc.)
  • Provides a base API to build other web-based Rive runtime wrappers (React, Angular, etc.)
  • Support advanced use cases by controlling the render loop (web-based game engines)

​
Quick Start

See our quick start example.

This example only demonstrates loading a .riv file resource in various ways and creating a Rive instance. The other sections detail more advanced use cases.

​
Getting started

Follow the steps below to integrate Rive into your web app.

The following instructions describe using the @rive-app/canvas package. Rive provides web-based packages like WebGL, Canvas, and Lite versions.

See Canvas vs WebGL for guidance on which package is the correct choice for your use case.

1

Install the dependency

We recommend always using the latest version. The versions listed below and in the examples may differ from the latest.

// Add the following script tag to your web page to get the latest version:


<script src="https://unpkg.com/@rive-app/canvas"></script>

// You can also pin to a specific version (See [here](https://www.npmjs.com/package/@rive-app/canvas) for the latest):


<script src="https://unpkg.com/@rive-app/canvas@2.24.0"></script>

// This will make a global `rive` object available, allowing you to access the Rive API via the `rive` entry point:

new rive.Rive({});

Not using Rive Text and Rive Audio? Consider using @rive-app/canvas-lite which is a smaller package variant.

2

Create a Canvas

Add a canvas element to your HTML where you want the Rive graphic to be displayed:

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

Create a Rive instance

To create a new instance of a Rive object, provide the following properties:

  • src: A string representing the URL of the hosted .riv file (as shown in the example below) or the path to the public asset .riv file. For more details, refer to Rive Parameters on how to properly use this property.
  • artboard - (Optional) A string representing the artboard you want to display. If not supplied the default is selected.
  • stateMachines - A string representing the name of the state machine you wish to play.
  • canvas - The canvas element where the animation will be rendered.
  • autoplay - A boolean indicating whether the animation should play automatically.
<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,
        // artboard: "Arboard", // Optional. If not supplied the default is selected
        stateMachines: "bumpy",
        onLoad: () => {
          r.resizeDrawingSurfaceToCanvas();
        },
    });
</script>

The resizeDrawingSurfaceToCanvas method ensures that the Rive animation is correctly scaled to fit the dimensions of the specified canvas element. By default, the canvas rendering surface might not match the exact size of the <canvas> element defined in your HTML, which can lead to blurry or incorrectly scaled graphics, especially on high-DPI or retina displays.

Calling this method adjusts the internal drawing surface so that the animation is rendered with crisp detail, matching the pixel density of the canvas. This is particularly important when:

  • The size of the canvas changes dynamically (e.g., if it is resized due to responsive layouts).
  • You want to ensure the animation remains sharp, regardless of device or screen resolution.

Best practices:

  • Call after load: It’s recommended to call resizeDrawingSurfaceToCanvas inside the onLoad callback to ensure that the Rive asset has been fully loaded before adjusting the drawing surface. This prevents any rendering issues.
  • Handling window resize: If your canvas size changes during the user’s interaction (such as when resizing the browser window), you should also listen for window resize events and call resizeDrawingSurfaceToCanvas to re-adjust the rendering surface:
window.addEventListener("resize", () => {
    r.resizeDrawingSurfaceToCanvas();
});

This way, the Rive animation will continue to look sharp and correctly scaled as the canvas size changes.

​
Complete example

Bringing it all together, here’s how to load a Rive graphic in a single HTML file.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Rive Hello World</title>
  </head>
  <body>
    <canvas id="canvas" width="500" height="500"></canvas>

    <script src="https://unpkg.com/@rive-app/canvas"></script>
    <script>
      const r = new rive.Rive({
        src: "https://cdn.rive.app/animations/vehicles.riv",
        canvas: document.getElementById("canvas"),
        autoplay: true,
        // artboard: "Arboard", // Optional. If not supplied the default is selected
        stateMachines: "bumpy",
        onLoad: () => {
          // Ensure the drawing surface matches the canvas size and device pixel ratio
          r.resizeDrawingSurfaceToCanvas();
        },
      });
    </script>
  </body>
</html>

​
Loading Rive files

See this example for the different ways to load in a .riv file, the options are:

  1. Hosted URL: Use a string representing the URL where the .riv file is hosted. Set this as the src attribute when creating a new Rive instance.
  2. Static Assets in the bundle: Provide a string with the path to a publicly accessible .riv file within your web project. Handle .riv files just like any other static asset (e.g., images or fonts) in your project.
  3. Fetching a file: Instead of using the src attribute, use the buffer attribute to load an ArrayBuffer when fetching a file. This is useful when reusing the same .riv file across multiple Rive instances, allowing you to load it only once.
  4. Reusing a Loaded File: Use the rivFile parameter to reuse a previously loaded Rive runtime file object, avoiding the need to fetch it again via the src URL or reload it from the buffer. This can significantly improve performance by eliminating redundant network requests and loading times, especially when creating multiple Rive instances from the same source. Unlike the src and buffer parameters, which require parsing under the hood to create a runtime file object, the riveFile parameter uses an already parsed object, including any loaded assets. See Caching a Rive File.

For more details, refer to the Rive Parameters section on the src property.

​
4. Clean up Rive

When working with a Rive instance, it’s important to properly clean it up when it’s no longer needed. This is especially necessary in scenarios where:

  • The UI containing Rive animations is no longer needed (e.g., when a modal with Rive graphics is closed).
  • The animation or state machine has completed and will not be shown or run again.

Under the hood, Rive creates various low-level objects (such as artboard instances, animation instances, and state machine instances) in C++, which need to be manually deleted to prevent memory leaks. If not cleaned up, these objects can consume unnecessary resources, potentially impacting your application’s performance.

Fortunately, the high-level JavaScript API simplifies this process. You don’t need to track every object created during the Rive instance lifecycle. Instead, you can clean up all associated objects with a single method call.

To clean up a Rive instance and free up resources, simply call the following method on your Rive instance:

const riveInstance = new Rive({...));
...
// When ready to cleanup
riveInstance.cleanup();

​
Rive runtime concepts

Learn how to interact with your Rive graphics during runtime.

Animation Playback

Configuring runtime animation playback properties.

Layout

Controlling your Rive graphic’s layout (fit and alignment) at runtime.

State Machine

Interacting with Rive state machines from runtime.

Text

Update Rive text at runtime.

Playing Audio

Runtime audio properties and controls.

Rive Events

Subscribe to Rive events at runtime.

Loading Assets

Loading and replacing assets (images, fonts, audio) dynamically at runtime.

Caching a Rive File

Cache and reuse a Rive file object across multiple Rive instances.

​
Additional Rive web resources

More in-depth Rive web documentation and advanced use cases.

Rive Parameters

API docs for the Rive instance.

Canvas vs WebGL

A guide to the different Rive web packages

FAQ

Frequently asked questions

Preloading WASM

Instructions on how to preload and self-host the rive WASM library.

Low-level API Usage

Control the Rive render loop and layout, and draw multiple artboards to the same canvas.

​
Examples

Was this page helpful?

Suggest editsRaise issue
FormatRive Parameters