Rive Parameters

API docs for the Rive instance

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

Parameters

You can set any of the following parameters on the Rive object when instantiating:

export interface RiveParameters {
  canvas: HTMLCanvasElement | OffscreenCanvas, // required
  src?: string, // one of src or buffer is required
  buffer?: ArrayBuffer, // one of src or buffer is required
  artboard?: string,
  animations?: string | string[],
  stateMachines?: string | string[],
  layout?: Layout,
  autoplay?: boolean,
  onLoad?: EventCallback,
  onLoadError?: EventCallback,
  onPlay?: EventCallback,
  onPause?: EventCallback,
  onStop?: EventCallback,
  onLoop?: EventCallback,
  onStateChange?: EventCallback,
  onAdvance?: EventCallback,
  assetLoader?: AssetLoadCallback,
  useOffscreenRenderer?: boolean,
  shouldDisableRiveListeners?: boolean,
}

  • canvas - (required) Canvas element to draw Rive animations onto.

  • src? - (optional) There are two optional ways to use src: either via URL to the .riv file, or a path to the public .riv asset to use. One of src or buffer must be provided.

    • URL - If you are hosting your .riv on some publicly accessible bucket/CDN (i.e. AWS, GCS, etc.), you can pass in the URL here.

      • Alternatively, with ES6, you may import the .riv file as a data URI. Depending on your bundle loader, you may need to use a plugin (i.e url-loader for Webpack) to properly parse and load in .riv files as a data URI string. See this project as a basic example on how to set this up

    • Path to public asset - This is a string path to the.riv public asset if bundled in your application. Note that this is not a relative path to the asset from wherever the current JS file is in. Treat the .riv as any other asset bundled in your application, such as an image or font. If your JS is compiled and run at the root of your web application, you must specify the path from the root to the location of the asset. For example, if your asset is in /public/foo.riv, and your JS is run from the root at /, you would specify: src: '/public/foo.riv' in this property.

  • buffer? - (optional) ArrayBuffer containing the raw bytes from a .riv file. One of src or buffer must be provided.

  • artboard? - (optional) Name of the artboard to use.

  • animations? - (optional) Name or list of names of animations to play.

Currently, Rive will play the first timeline animation it finds if no stateMachines or animations parameter is provided, however, in a future major version of rive-wasm, the default will be to play the first state machine it finds.

  • stateMachines? - (optional) Name or list of names of state machines to load.

Note: You should only provide a single state machine string for stateMachines. Running multiple state machines of the same artboard at the same time may cause unintended consequences.

In a future major version of rive-wasm, stateMachines will be a singular string you pass in.

  • layout? - (optional) Layout object to define how animations are displayed on the canvas.

  • autoplay? - (optional) If true, the animation will automatically start playing when loaded. Defaults to false.

  • onLoad? - (optional) Callback that gets fired when the .riv file loads.

  • onLoadError? - (optional) Callback that gets fired when an error occurs loading the .riv file.

  • onPlay? - (optional) Callback that gets fired when the animation starts playing.

  • onPause? - (optional) Callback that gets fired when the animation pauses.

  • onStop? - (optional) Callback that gets fired when the animation stops playing.

  • onLoop? - (optional) Callback that gets fired when the animation completes a loop.

  • onStateChange? - (optional) Callback that gets fired when a state change occurs.

  • onAdvance? - (optional) Callback that gets fired every frame when the Artboard has advanced.

  • assetLoader? - (optional) Callback that gets invoked for every asset detected in a Rive file (whether included or excluded). The callback is passed a reference to a Rive FileAsset and associated bytes for the file (if the asset is embedded in the file). In this callback, you'll determine whether or not to load the asset in your app yourself, or have Rive do it for you. For more details and examples, see the Loading Assets page.

  • useOffscreenRenderer? - (optional) Boolean flag to determine whether to use a shared offscreen WebGL context rather than create its own WebGL context for this instance of Rive. This is only relevant for the @rive-app/webgl package. If you are displaying multiple Rive animations, it is highly encouraged to set this flag to true. Defaults to false.

  • shouldDisableRiveListeners? - (optional) Boolean flag to disable setting up Rive Listeners on the <canvas> element, thus preventing any event listeners from being set up on the element.

    • Note: Rive Listeners by default are not set up on a <canvas> element if there is no playing state machine, or a state machine without any Rive Listeners set up on the state machine

APIs

The following API's are available after instantiating Rive:

play()

play(names?: string | string[], autoplay?: true): void

Plays a specified linear timeline animation(s) or state machine via the passed-in name. Useful if you have either programmatically called pause() or stop() or set autoplay: false when instantiating Rive. If no name is passed in, it plays all instantiated timeline animations or state machines (or the default animation if neither is instantiated).

Example:

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: false,
  canvas: document.querySelector("canvas"),
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // Play the 'bumpy' state machine
  riveInstance.play("bumpy");
};

pause()

pause(names?: string | string[]): void

Pauses a specified linear timeline animation(s) or state machine via the passed-in name. Useful if you want to programmatically pause the playing animation and pause the render loop. You may want to use this API too if the associated Rive instance's <canvas> element is scrolled offscreen. If no name is passed in, it pauses all instantiated timeline animations or state machines.

Example:

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // Pause the 'bumpy' state machine
  riveInstance.pause("bumpy");
};

stop()

stop(names?: string | string[]): void

Stops a specified linear timeline animation(s) or state machine via the passed-in name. Useful if you want to programmatically stop the playing animation and render loop. You may want to use this API too if the associated Rive instance's state machine is "done," or in an exit state. If no name is passed in, it stops all instantiated timeline animations or state machines.

Example:

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // Stop the 'bumpy' state machine
  riveInstance.stop("bumpy");
};

reset()

interface RiveResetParameters {
  artboard?: string;
  animations?: string | string[];
  stateMachines?: string | string[];
  autoplay?: boolean;
}

reset(params?: RiveResetParameters): void

Resets the Rive Artboard, linear timeline animations, and/or the state machine from the start (or entry state) based on the parameters passed in. Implicitly, this method will also cleanup any existing instances (Artboard, Animation, and/or State Machine) created already before creating new ones. The instantiated timeline animation or state machine will play immediately depending on the autoplay property passed in.

Example:

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
  stateMachines: "bumpy"
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // Reset the 'bumpy' state machine
  riveInstance.reset({
    stateMachines: "bumpy",
    autoplay: true,
  });
};

on()

on(type: EventType, callback: EventCallback): void

Similar to the Web API's addEventListener functionality on DOM elements, you can subscribe to specific "events" in a render loop cycle via providing an EventType enum and a callback for the runtime to invoke with different parameters depending on the event you want to subscribe to.

EventType has the following enums to subscribe to that may or may not trigger during the lifespan of the Rive animation/state machine:

export enum EventType {
  Load = "load", // When Rive has successfully loaded in the Rive file
  LoadError = "loaderror", // When Rive cannot load the Rive file
  Play = "play", // When Rive plays an entity or resumes the render loop
  Pause = "pause", // When Rive pauses the render loop and playing entity
  Stop = "stop", // When Rive stops the render loop and playing entity
  Loop = "loop", // (Singular animations only) When Rive loops an animation 
  Advance = "advance", // When Rive advances the animation in a frame
  StateChange = "statechange", // When a Rive state change is detected
  RiveEvent = "riveevent", // When a Rive Event gets reported
}

Example

import {Rive, EventType} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "/rating-animation.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
  stateMachines: "State Machine 1",
});

const riveEventHandler = (event) => {
  if (event.data.name === "rating1") {
    // Send feedback to API
  } else if (event.data.name === "redirect") {
    const newAnchorTag = document.createElement("a");
    const {url, target} = (event as rc.OpenUrlEvent);
    url && newAnchorTag.setAttribute("href", url);
    target && newAnchorTag.setAttribute("target", target);
    if (url) {
      newAnchorTag.click();
    }
  }
};

riveInstance.on(EventType.RiveEvent, riveEventHandler);

off()

off(type: EventType, callback: EventCallback): void

Similar to the Web API's removeEventListener functionality on DOM elements, you can unsubscribe to specific "events" in a render loop cycle via providing an EventType enum and the callback reference that was registered via the on() API.

import {Rive, EventType} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "/rating-animation.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
  stateMachines: "State Machine 1",
});

const riveEventHandler = (event) => {
  if (event.data.name === "rating1") {
    // Send feedback to API
  } else if (event.data.name === "redirect") {
    const newAnchorTag = document.createElement("a");
    const {url, target} = (event as rc.OpenUrlEvent);
    url && newAnchorTag.setAttribute("href", url);
    target && newAnchorTag.setAttribute("target", target);
    if (url) {
      newAnchorTag.click();
    }
  }
};

riveInstance.on(EventType.RiveEvent, riveEventHandler);
// ...
riveInstance.off(EventType.RiveEvent, riveEventHandler);

removeAllEventListeners()

removeAllEventListeners(type?: EventType): void

This effectively removes all event listening subscriptions for a single particular EventType that may have been added via the on() API.

scrub()

scrub(animationNames?: string | string[], value?: number): void

Scrubs through (a) linear timeline animation(s) by a specified amount of seconds.

Note: This will not do anything if you are playing through a state machine. This only applies if you are using instantiated animations through the animations property.

cleanup()

cleanup(): void

This API is important to call, as it will stop the animation render loop, and clean up all created instances for the Rive file, artboard, linear timeline animation(s), state machine, and the renderer. The reason it's important to delete these instances is because these entities hold generated C++ references through WASM behind-the-scenes, and therefore will not automatically get garbage collected like normal JS objects, and must be "cleaned up" manually, to prevent memory leaks. Once you are done with the Rive instance (i.e., a state machine has finished running, a user is navigating off the page, etc.), call .cleanup() to ensure all underlying memory allocated is freed up.

If you want to present a different Artboard from the same Rive file dynamically, you can call cleanupInstances() which will only delete the Artboard, animation, and state machine instances (but not the Rive file or renderer object, which you can still reuse).

Example:

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
  stateMachines: "bumpy"
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // Cleanup Rive before navigating user off page
  riveInstance.cleanup();
  window.location.href = "https://google.com";
};

cleanupInstances()

Similar to cleanup(), but will only clean up instances for the Artboard, linear timeline animation(s), and/or state machine, thus allowing you to re-initialize a different Artboard from the same Rive file, different timeline animation(s), or a different state machine. You can do this with reset().

load()

interface RiveLoadParameters {
  src?: string;
  buffer?: ArrayBuffer;
  autoplay?: boolean;
  artboard?: string;
  animations?: string | string[];
  stateMachines?: string | string[];
  useOffscreenRenderer?: boolean;
  shouldDisableRiveListeners?: boolean;
}

load(params: RiveLoadParameters): void

Replace the existing Rive instance with a new one, with potentially new parameters (including a new src file). This API also implicitly cleans up existing references to the old animation(s)/state machine/artboard. The backing WASM code that powers the Rive Web (JS) runtime shouldn't have to be loaded in again, so there should be no other network overhead unless you are loading in a new Rive file over the web.

resizeToCanvas()

resizeToCanvas(): void

This sets the layout bounds to the current canvas size. You may want to call this if your canvas is resized.

resizeDrawingSurfaceToCanvas()

resizeDrawingSurfaceToCanvas(customDevicePixelRatio?: number): void

This resets the <canvas> width and height properties to render at its current bounding rect size (CSS height and width properties) with the browser's devicePixelRatio in mind. This prevents blurry output on high-dpi screens (i.e., a <canvas> that is 500x500 on the page may render with an internal area size of 1000x1000 while still maintaining its original canvas size). This calls resizeToCanvas() implicitly. It's recommended to call this in the onLoad callback.

You may also pass in a single number parameter when calling this function that forces a specific device pixel ratio to be used in calculating the canvas width and height. This may be helpful when displaying Rives on a mobile device where you could have a more performant graphic by overriding the window's devicePixelRatio with a lower value.

In a future major version of this runtime, this API may be called internally on initialization by default, with an option to opt-out if you have specific width and height properties you want to set on the canvas

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
  stateMachines: "bumpy",
  onLoad: () => {
    riveInstance.resizeDrawingSurfaceToCanvas();
  },
});

stateMachineInputs()

class StateMachineInput {
  // name of the input
  public get name: string
  // value of the input (for number or boolean inputs)
  public get value: number | boolean
  // directly set the input value (for number or boolean inputs)
  public set value: number | boolean
  // Method call to fire a trigger input
  public fire(): void
}

stateMachineInputs(stateMachineName: string): StateMachineInput[]

Returns a list of state machine input objects from the given state machine name passed in (if the state machine has been instantiated). Use these state machine inputs to drive the state machine forward.

const riveInstance = new rive.Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  canvas: document.getElementById('canvas'),
  autoplay: true,
  stateMachines: 'bumpy',
  onLoad: () => {  
    // Get the inputs via the name of the state machine
    const inputs = riveInstance.stateMachineInputs('bumpy');
    // Find the input you want to set a value for, or trigger
    const bumpTrigger = inputs.find(i => i.name === 'bump');
    button.onclick = () => bumpTrigger.fire();
  },
});

stopRendering()

stopRendering(): void

Stops the render loop, and can only be resumed with startRendering(). This is useful for situations when the <canvas> is not visible. The React runtime utilizes this for that particular situation implicitly.

startRendering()

startRendering()

Starts the render loop if it has been previously stopped. It will have no effect if the render loop is already active.

getTextRunValue()

getTextRunValue(textRunName: string): string | undefined

Returns the text value of the text run component (from the hierarchy of your .riv file) you want to retrieve from. Returns undefined if the text run cannot be queried from the active Artboard (you may see console warnings in this case for further guidance).

setTextRunValue()

setTextRunValue(textRunName: string, textValue: string): void

Sets the text value of the text run component (from the hierarchy of your .riv file) you specify via textRunName. You may see console warnings if the text run cannot be queried from the active Artboard, and thus the provided textValue you want to set on the run may not be successful.

resolveAnimationFrame()

resolveAnimationFrame(): void

You only need to use this function if you are using Rive's low-level APIs to build the render loop manually and are integrating Rive into your existing requestAnimationFrame() loop

Resolves deferred drawing commands with the renderer. You must call this at the end of your render loop if you decide to use your own requestAnimationFrame() loop and are adding Rive graphics into it. Otherwise, if you are using Rive's wrapped rAF loop (i.e., rive.requestAnimatimationFrame() ), you do not need to call this method, as Rive will worry about resolving any rendering calls related to Rive graphics.

See example usage below:

let lastTime = 0;
function draw(time) {
  if (!lastTime) {
    lastTime = time;
  }
  const elapsedMs = time - lastTime;
  const elapsedSeconds = elapsedMs / 1000;
  lastTime = time;

  renderer.clear();
  
  if (artboard) {
    if (stateMachine) {
      stateMachine.advance(elapsedSeconds);
    }
    if (animation) {
      animation.advance(elapsedSeconds);
      animation.apply(1);
    }
    artboard.advance(elapsedSeconds);
    renderer.save();

    renderer.align(
      rive.Fit.contain,
      rive.Alignment.center,
      {
        minX: 0,
        minY: 0,
        maxX: canvas.width,
        maxY: canvas.height,
      },
      artboard.bounds
    );

    // Pass along our Renderer to the artboard, so that it can draw onto the canvas
    artboard.draw(renderer);
    renderer.restore();
    renderer.flush();
  }

  // Needed to actually resolve a queue of drawing and rendering calls with our Renderer
  // Note: ONLY needed if using a normal JS requestAnimationFrame, rather than our wrapped
  // one in the rive API
  rive.resolveAnimationFrame();

  // Call the next frame!
  requestAnimationFrame(draw);
}
// Start the animation loop
requestAnimationFrame(draw);

Debugging Tools

contents

Unlike other APIs that you call as a method on the Rive instance, contents is just a property on the Rive instance you can log to the console to see an object hierarchy of what was loaded in from the Rive file. This is useful to see what Rive file was loaded in, all the artboards associated with the file, animations and state machines, state machine inputs, and more. It's also useful if you don't have access to the file to inspect in the Rive editor directly.

Example:

const riveInstance = new rive.Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  canvas: document.getElementById('canvas'),
  autoplay: true,
  stateMachines: 'bumpy',
  onLoad: () => {  
    // Log the contents of the Rive file
    console.log(riveInstance.contents);
  },
});

enableFPSCounter()

type FPSCallback = (fps: number) => void;

enableFPSCounter(fpsCallback?: FPSCallback): void

Reports frames-per-second (FPS) for the runtime. You can supply a callback to handle how to display or ingest the data, or if you don't provide a callback, calling this API will append a fixed-position <div> in the top-right corner of the page, reading out the FPS. Call this after Rive has initialized in the onLoad callback, or at another point in time.

disableFPSCounter()

disableFPSCounter(): void

Disables the FPS reporting for the runtime.

Other

Other API's and properties are provided to report playing/paused/stopped entities in the Rive instance.

source

Property to get the src attribute in the Rive instance

activeArtboard

Property to get the name of the active artboard

animationNames

Property to get an array of all animation names on the loaded in Artboard (even if the animations are not specified at instantiation)

stateMachineNames

Property to get an array of all state machine names on the loaded in Artboard (even if the state machine(s) are not specified at instantiation)

playingAnimationNames

Property to get an array of all active playing timeline animation names on the Rive instance (if you are playing a state machine, this will not return the currently active state timeline animations)

playingStateMachineNames

Property to get an array of all active playing state machine names on the Rive instance

pausedAnimationNames

Property to get an array of all active paused timeline animation names on the Rive instance (if you are playing a state machine, this will not return the currently active state timeline animations)

pausedStateMachineNames

Property to get an array of all active paused state machine names on the Rive instance

isPlaying

Property that returns true if any animation is playing

isPaused

Property that returns true if all instanced animations are paused

isStopped

Property that returns true if no instanced animations are playing or paused

bounds

Property that returns the bounds of the Artboard

layout (get/set)

Property to either get or set a Rive Layout

Example:

import {Rive, Layout, Fit, Alignment} from '@rive-app/canvas';

const riveInstance = new rive.Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  canvas: document.getElementById('canvas'),
  autoplay: true,
  stateMachines: 'bumpy',
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // Set new Layout
  riveInstance.layout = new Layout({
    fit: Fit.Cover,
    alignment: Alignment.TopCenter,
  });
};

Last updated