Rive

ディレクトリ構成

skills/rive/
  SKILL.md
  references/
    runtimes-web/
      README.md
      packages.md
      rive-constructor.md
      rive-methods.md
      layout.md
      state-machine-playback.md
      data-binding.md
      loading-assets.md
      fonts.md
      audio.md
      events.md
      rive-file.md
      preloading-wasm.md
    runtimes-react/
      README.md
      overview.md
      use-rive.md
      use-state-machine-input.md
      layout.md
      data-binding.md
    concepts/
      README.md
      state-machine.md
      states.md
      transitions.md
      layers.md
      inputs.md
      listeners.md
      data-binding.md
      view-models.md
      instances.md
      properties.md
      converters.md
      enums.md
      events.md
      layout.md
  samples/
    README.md
    web-basic.md
    react-interactive.md
    state-machine-control.md
  scripts/
    README.md
    install.md

探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す 2. そのカテゴリの README.md を参照して目的のページを特定する 3. 該当ページの .md を Read して詳細を確認する

タスク → カテゴリ マッピング

Converters

Transformation nodes that modify a ViewModel property value before it is applied to a binding target. Converters adapt data to match the type or range expected by a scene element, and can be chained sequentially.

Signature / Usage

Converters are configured in the editor when setting up a binding or a "View Model Change" listener action. No runtime code is required — converters run automatically as part of the data binding pipeline.

ViewModel Property → [Converter A] → [Converter B] → Scene Property

Options / Props

String Converters

Number Converters

Boolean Converters

List Converters

Color Converters

Custom

Notes

• Multiple converters can be chained in sequence; the output of each feeds into the input of the next.
• Many converter properties (e.g., a Range Map's maximum value, a Formula's multiplier) are themselves bindable to ViewModel properties, enabling dynamic behavior.
• The "System Enum to Uint" converter is applied automatically when binding an Enum property to a numeric scene property.

Related

• Data Binding
• Properties
• Enums

Data Binding

The system that connects data stored in ViewModels to properties in a Rive scene. When data changes, the scene updates automatically; changes in the scene can optionally write back to the data source.

Signature / Usage

Data binding is configured in the editor and consumed at runtime via the ViewModel instance API.

// Runtime: get ViewModel instance and read/write properties
const vmi = riveInstance.viewModelInstance;

// Number
const hp = vmi.number("health");
hp.value = 80;

// String
const label = vmi.string("playerName");
label.value = "Ada";

// Boolean
const active = vmi.boolean("isActive");
active.value = true;

// Trigger
const hit = vmi.trigger("onHit");
hit.trigger();

// Observe changes driven by the state machine
hp.on((event) => console.log("health changed:", event.data));

Options / Props

Notes

• Binding is established in the editor: right-click a property → "Data Bind" → select ViewModel property. A green highlight indicates a valid binding; yellow indicates a type mismatch.
• Binding decouples data from scene hierarchy: reorganizing elements or renaming properties in the editor does not require runtime code changes.
• Data can be updated from the editor, runtime code, state machines, or scripting.
• The Path binding option selects which specific nested ViewModel instance binds when ViewModels are hierarchically composed.
• Property observers (.on()) fire after state machine advances apply the change, not immediately on assignment.

Related

• View Models
• Instances
• Properties
• Converters
• Enums

Enums

Data types that restrict a ViewModel property to a predefined set of named options. Enums prevent invalid values and make designer intent explicit when a property should only hold a fixed set of states (e.g., game modes, layout variants, animation states).

Signature / Usage

Enums are defined in the Data panel and used as ViewModel property types. At runtime they are accessed via the ViewModel Instance API.

const vmi = riveInstance.viewModelInstance;
const mode = vmi.enum("gameMode");
console.log(mode.value); // e.g., "easy"
mode.value = "hard";

Options / Props

Creating a Custom Enum (editor)

1. Open the Data panel → click + → select Enum. 2. Add named options. 3. Add an Enum property to a ViewModel and select the custom enum type. 4. Set the default value in the right sidebar.

Notes

• Enum values are referenced by their string name at runtime.
• When binding an Enum property to a numeric scene property, the "System Enum to Uint converter" is applied automatically.
• Enums control Solo visibility: map each enum value to a corresponding Solo to switch between component variants; a "Convert to Number" converter is required in this case.
• Enums provide stronger type safety than raw strings or numbers for fixed-option properties.

Related

• Properties
• Data Binding
• Converters

Events

Signals emitted from within a Rive artboard to notify the runtime that something has happened. Events originate from timelines, states, transitions, or listeners and are consumed via runtime callbacks or ViewModel property observers.

Signature / Usage

// Playback lifecycle callbacks (provided in Rive constructor)
const r = new Rive({
  src: "animation.riv",
  onPlay:        (event) => console.log("playing:", event.data),   // string[]
  onPause:       (event) => console.log("paused:",  event.data),   // string[]
  onStop:        (event) => console.log("stopped:", event.data),   // string[]
  onLoop:        (event) => console.log("looped:",  event.data),   // LoopEvent
  onStateChange: (event) => console.log("state:",   event.data),   // string[]
});

// Alternative: subscribe after construction
r.on(EventType.StateChange, (event) => {
  console.log("new state(s):", event.data); // string[] of state names
});

// Rive custom events (Report Event) via ViewModel property observers
const prop = vmi.boolean("wasTriggered");
prop.on((event) => console.log("custom event data:", event.data));

Options / Props

Playback Lifecycle Callbacks

Rive Event Types (editor-defined)

Signaling Events (editor)

Notes

• onStateChange delivers the string name(s) of the newly active states; use these to react to state machine transitions in application logic.
• Custom events (Report Event) fired from Rive are now consumed via ViewModel property observers (.on()) rather than a dedicated event API, because the general "Rive Events" system is deprecated in favor of Data Binding.
• onLoop LoopType values: OneShot, Loop, PingPong.
• All callbacks can also be registered/deregistered dynamically using riveInstance.on(EventType, callback) and riveInstance.off(EventType, callback).

Related

• State Machine
• Listeners
• Data Binding

Inputs

Named values attached to a State Machine that drive transition conditions and blend parameters. Inputs are the primary mechanism for controlling a state machine from runtime code or listeners.

Signature / Usage

Inputs are defined in the State Machine panel and referenced by name in transition conditions. At runtime they are accessed via the stateMachineInputs() API (legacy) or Data Binding (recommended).

// Legacy API (deprecated — prefer Data Binding)
const inputs = riveInstance.stateMachineInputs("State Machine 1");
const hover   = inputs.find(i => i.name === "isHovered");  // Boolean
const speed   = inputs.find(i => i.name === "speed");       // Number
const clicked = inputs.find(i => i.name === "onClick");     // Trigger

hover.value = true;    // set boolean
speed.value = 0.8;     // set number
clicked.fire();        // fire trigger

Options / Props

Notes

• Inputs are referenced by name (string); names must match exactly between editor and runtime code.
• The StateMachineInput object exposes: .name (string), .value (number | boolean, read/write), .type (StateMachineInputType enum), .fire() (trigger only).
• Direct input mutation is deprecated as of the Data Binding era. The recommended approach is to bind inputs to ViewModel properties and update the ViewModel at runtime instead.
• Triggers automatically reset after one state machine advance frame; they do not need to be manually reset to false.

Related

• State Machine
• Transitions
• Data Binding

Instances

ViewModel Instances are the concrete data containers created from a ViewModel blueprint. Each instance holds its own independent set of property values and can be bound to an artboard or component.

Signature / Usage

// Three factory methods on a ViewModel
const vm = riveInstance.viewModel("Player");

const blank    = vm.instance();                  // all properties at type defaults
const fallback = vm.defaultInstance();           // the instance marked default in the editor
const byName   = vm.instanceByName("Player 1"); // lookup by name set in editor

Notes

• Multiple instances can exist for the same ViewModel simultaneously, each with independent values.
• The active instance on a Rive object is accessible via riveInstance.viewModelInstance.
• Instances can be swapped at runtime to change the data set driving an artboard.
• To manage instances in the editor: select a ViewModel → click the Controls icon → use + / - to add or remove, double-click to rename, click an instance to edit its property values.
• Instances marked as "exported" are bundled inside the .riv file; unmark to reduce file size when the instance is only needed during design.

Related

• View Models
• Data Binding
• Properties

Layers

Independent parallel animation tracks within a single State Machine. Each layer runs its own graph of states and transitions, allowing multiple animations to play simultaneously on the same artboard.

Signature / Usage

Layers appear as tabs in the Layers panel of the State Machine editor. Each layer has its own Entry, Exit, and Any states.

State Machine
├── Layer 1 (leftmost) — lower priority
│   └── [states & transitions]
├── Layer 2
│   └── [states & transitions]
└── Layer N (rightmost) — highest priority

Notes

• Each layer plays one animation at a time, but multiple layers run concurrently, enabling animation blending.
• When layers control the same object properties, the rightmost layer takes priority.
• Use layers to separate concerns: e.g., a background animation in Layer 1, character interaction logic in Layer 2.
• Managing layers:
• Add: click + in the Layers tab
• Reorder: drag and drop
• Right-click options: Delete, Duplicate, Disable/Enable
• The Exit State in a layer stops only that layer; other layers continue running.

Related

• State Machine
• States

Layout

The Layout configuration controls how a Rive artboard is scaled and positioned within its host container. It defines the Fit mode (scaling strategy) and Alignment (anchor position), and optionally constrains the drawing region.

Signature / Usage

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

const r = new Rive({
  src: "animation.riv",
  canvas: document.getElementById("canvas"),
  layout: new Layout({
    fit: Fit.Contain,            // default
    alignment: Alignment.Center, // default
    layoutScaleFactor: 1,        // optional scale multiplier (used with Fit.Layout)
    minX: 0,                     // optional bounds for partial rendering
    minY: 0,
    maxX: 0,
    maxY: 0,
  }),
  autoplay: true,
});

// Update layout responsively
window.addEventListener("resize", () => {
  r.layout = new Layout({ fit: Fit.Cover, alignment: Alignment.TopCenter });
  r.resizeDrawingSurfaceToCanvas();
});

Options / Props

Fit Modes

Alignment Options

Layout Class Constructor

Notes

• Alignment has no effect for Fit.Fill and Fit.Layout, since those modes expand the artboard to match the container exactly.
• For responsive layouts: set fit to Fit.Layout, configure artboard constraints in the editor, then call resizeDrawingSurfaceToCanvas() on window resize events (and on device pixel ratio changes).
• The layout property on a live Rive instance is a getter/setter — assign a new Layout object to update it without recreating the instance.
• Layout in the editor (Row/Column-based positioning of child objects) is a separate concept from the runtime Layout class described here; the editor layout system controls intra-artboard element positioning.

Related

• State Machine

Listeners

State Machine components that respond to user interactions (pointer events) or internal changes (ViewModel property changes, component events) and translate them into actions — updating data, firing events, or repositioning objects — without requiring runtime code.

Signature / Usage

A listener is configured entirely in the editor. Each listener has three parts: a Target, a Condition, and one or more Actions.

Listener
├── Target       — shape/group acting as a hit area, or an Artboard/Component
├── Condition    — what triggers the listener
└── Action(s)   — what happens when triggered

Options / Props

Target

Condition

Action

Notes

• Opaque Target: When disabled, pointer events pass through the hit area and can trigger multiple overlapping listeners simultaneously.
• Converters can be applied to "View Model Change" actions when mapping one property to another (e.g., incrementing a number).
• Listeners enable fully designer-authored interactivity without any runtime code for common pointer interactions.

Related

• State Machine
• Inputs
• Data Binding
• Events

Properties

Individual data fields within a ViewModel. Each property has a name, a type, and a value. Properties are bound to scene elements in the editor and read/written at runtime through the ViewModel Instance API.

Signature / Usage

const vmi = riveInstance.viewModelInstance;

// Number
const score = vmi.number("score");
score.value = 42;

// String
const name = vmi.string("userName");
name.value = "Ada";

// Boolean
const visible = vmi.boolean("isVisible");
visible.value = false;

// Color (RGBA hex string or numeric encoding depending on runtime)
const tint = vmi.color("primaryColor");

// Enum
const mode = vmi.enum("gameMode");
mode.value = "hard";

// Observe a property change (fires after state machine advance)
score.on((event) => console.log(event.data));
score.off(); // remove all observers

Options / Props

Notes

• Properties are created in the Data panel; add via "Add View Model Property" and choose the type.
• Property names are strings and must match exactly in runtime code.
• A property can be bound in multiple directions: Source→Target (ViewModel drives scene), Target→Source (scene drives ViewModel), or Bidirectional.
• The "Bind Once" flag applies the value only at startup and ignores subsequent changes — useful for static initialization.
• Observers (.on()) fire after state machine advances propagate changes, not immediately on .value assignment.

Related

• View Models
• Data Binding
• Converters
• Enums

concepts

State Machine

A visual framework for connecting animations and defining interactive transition logic within a Rive artboard. Every artboard includes one default state machine; additional state machines can be created as needed.

Signature / Usage

The State Machine replaces the timeline when selected in the editor. It consists of a graph workspace where states and transitions are arranged to define how animations flow in response to inputs and events.

Artboard
└── State Machine
    ├── Layers (one or more)
    │   ├── Entry State  → (transition) → Animation State
    │   ├── Animation State(s)
    │   ├── Any State
    │   └── Exit State
    ├── Inputs (Boolean / Number / Trigger)
    └── Listeners

Options / Props

Notes

• Each state machine layer plays one animation at a time.
• Multiple layers can run concurrently to blend animations; rightmost layer takes priority when properties conflict.
• State machines are the recommended mechanism for interactivity — direct animation playback control at runtime is deprecated in favor of state machines driven by Data Binding.

Related

• States
• Transitions
• Layers
• Inputs
• Listeners

States

Nodes in the State Machine graph that represent distinct animation conditions. Each state holds a timeline animation (or blend of animations) that plays while the state is active.

Signature / Usage

States appear as nodes on the State Machine graph. They are connected by transitions and activated according to input conditions.

State Machine Layer
├── Entry State         (auto-included)
├── Exit State          (auto-included)
├── Any State           (auto-included)
└── [User States]
    ├── Single Animation State
    ├── 1D Blend State
    └── Additive Blend State

Options / Props

Notes

• State properties include: animation selection, playback speed (positive = forward, negative = reverse), and transitions.
• Actions can be triggered at the start or end of a state (e.g., set a property, fire an event).
• 1D Blend States are commonly used for things like health bars and loading indicators.
• Additive Blend States support "by value" (baseline, uncontrolled) and "by property" (controlled via Number inputs) blending modes.

Related

• State Machine
• Transitions
• Inputs

Transitions

Directed connections between states in the State Machine graph that define when and how the machine moves from one state to another.

Signature / Usage

Create a transition by hovering over the edge of a state until an ellipse appears, then dragging to the destination state. Multiple transitions between the same states create "or" (any-match) logic; multiple conditions on one transition create "and" (all-match) logic.

State A --[condition(s)]--> State B

Options / Props

Notes

• Condition types:
• Boolean — fires when a named input equals true or false
• Number — fires when a named input satisfies an equality or comparison (=, >, <)
• Trigger — fires once when the named trigger input is activated
• Custom Script — complex conditions via scripting API
• Multiple transitions from the same source state act as an "or": whichever condition is satisfied first wins.
• Longer durations create smoother blending between state animations.
• Actions on a transition can be set to run at transition start or completion.

Related

• State Machine
• States
• Inputs

ViewModels

Reusable data blueprints that define the structure of data used in a Rive scene. A ViewModel defines which properties exist and their types; ViewModel Instances hold the actual values.

Signature / Usage

ViewModels are created in the Data panel. At runtime, instances are obtained from the Rive instance.

// Retrieve a ViewModel and create an instance
const viewModel = riveInstance.viewModel("Car");

const vmiBlank   = viewModel.instance();              // blank instance (default values)
const vmiDefault = viewModel.defaultInstance();       // instance marked as default in editor
const vmiNamed   = viewModel.instanceByName("Race1"); // named instance

Options / Props

ViewModel Properties

Connection Patterns

Notes

• A ViewModel itself stores no values — it is a schema. Instances store values.
• When a ViewModel is created, Rive automatically generates one instance named "Instance" for immediate editor testing.
• Multiple instances can share the same ViewModel structure while holding independent data.
• By default, instances are exported inside .riv files. Disable export for development-only instances to keep file sizes small.
• ViewModels support nested composition: a ViewModel property can reference another ViewModel, enabling parent–child data hierarchies.

Related

• Data Binding
• Instances
• Properties

Data Binding

Connects React application state to Rive animated elements through View Models and View Model Instances. Replaces the deprecated useStateMachineInput pattern.

Signature / Usage

import { useRive, useViewModel, useViewModelInstance, useViewModelInstanceBoolean } from '@rive-app/react-webgl2';

export default function Example() {
  const { rive, RiveComponent } = useRive({
    src: 'your_file.riv',
    autoBind: true,
  });

  const viewModel = useViewModel(rive);
  const instance = useViewModelInstance(viewModel, { useDefault: true, rive });

  const { value: isActive, setValue: setIsActive } =
    useViewModelInstanceBoolean('isToggleOn', instance);

  return (
    <>
      <RiveComponent />
      <button onClick={() => setIsActive(!isActive)}>Toggle</button>
    </>
  );
}

Options / Props

useViewModel

useViewModel(rive: Rive | null, options?: { name?: string; index?: number }): ViewModel | null

useViewModelInstance

useViewModelInstance(viewModel: ViewModel | null, options?: UseViewModelInstanceOptions): ViewModelInstance | null

Property hooks

All property hooks share the signature:

useViewModelInstance<Type>(propertyPath: string, instance: ViewModelInstance | null, options?): PropertyState

Use forward-slash-delimited paths for nested properties (e.g. 'settings/theme/name').

Notes

• Hook values update automatically (triggering re-renders) when the Rive instance changes a bound property.
• For triggers, use the onTrigger callback option rather than checking return values.
• Properties require a state machine or artboard advance to apply changes to bound elements.
• autoBind: true in useRive is the preferred pattern when using the file's default View Model and instance; the bound instance is also accessible via rive?.viewModelInstance.
• List properties can contain mixed View Model types in a single list.
• When setting image properties, always call decodedImage.unref() after passing it to setValue to avoid memory leaks.

Related

• useRive
• useStateMachineInput

Layout Props

Controls how a Rive artboard scales and positions itself within its container. Pass a Layout instance to the layout prop of the Rive component or the useRive hook.

Signature / Usage

new Layout(options?: LayoutOptions): Layout

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

export const Example = () => (
  <Rive
    src="https://cdn.rive.app/animations/vehicles.riv"
    layout={new Layout({ fit: Fit.Contain, alignment: Alignment.TopCenter })}
  />
);

// With useRive hook
import { useRive, Layout, Fit, Alignment } from '@rive-app/react-webgl2';

export default function Example() {
  const { RiveComponent } = useRive({
    src: 'my-file.riv',
    layout: new Layout({
      fit: Fit.Cover,
      alignment: Alignment.TopCenter,
    }),
    autoplay: true,
  });

  return <RiveComponent />;
}

Options / Props

LayoutOptions

Fit Values

Alignment Values

TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight

Notes

• Fit.Layout automatically responds to window resizing and device pixel ratio changes.
• Providing minX/minY/maxX/maxY overrides the alignment setting.
• layoutScaleFactor is only meaningful when fit is Fit.Layout.

Related

• Overview
• useRive

React Runtime Overview

The Rive React runtime provides two primary packages for integrating Rive animations into React applications. Choose a package based on which rendering backend you need.

Signature / Usage

# Recommended — Rive Renderer with WebGL2
npm i --save @rive-app/react-webgl2

# Canvas-based alternative
npm i --save @rive-app/react-canvas

import Rive from '@rive-app/react-webgl2';

export const Simple = () => (
  <Rive
    src="https://cdn.rive.app/animations/vehicles.riv"
    stateMachines="bumpy"
  />
);

Options / Props

Notes

• The default export (Rive) is a drop-in component for simple use cases; use useRive for advanced control.
• @rive-app/react-webgl2: enable the draft WEBGL_shader_pixel_local_storage Chrome extension to get full performance benefits of the Rive Renderer. Browsers without it fall back to MSAA.
• Rive does not instantiate until <RiveComponent /> is rendered — the underlying <canvas> must be present in the DOM.
• The canvas initially defaults to 0×0; set sizing via className or a wrapper container.
• For conditional rendering, isolate useRive in a dedicated wrapper component to prevent animation restarts during re-renders.

Related

• useRive Hook
• Layout Props
• Data Binding

runtimes-react

useRive

Primary hook for accessing the Rive runtime with full control. Returns a RiveComponent for rendering and the underlying rive instance for imperative control.

Signature / Usage

useRive(riveParams: UseRiveParameters | null, opts?: UseRiveOptions): RiveState

import { useRive } from '@rive-app/react-webgl2';

export default function Example() {
  const { rive, RiveComponent } = useRive({
    src: 'https://cdn.rive.app/animations/vehicles.riv',
    stateMachines: 'bumpy',
    autoplay: false,
  });

  return (
    <RiveComponent
      onMouseEnter={() => rive && rive.play()}
      onMouseLeave={() => rive && rive.pause()}
    />
  );
}

Options / Props

UseRiveParameters (riveParams)

Passed directly to the underlying Rive web runtime object. Accepts null or undefined for deferred / conditional initialization.

UseRiveOptions (opts)

React-specific options passed as the second argument.

RiveState (return value)

Notes

• RiveComponent wraps the <canvas> inside a <div>. style/className props target the <div> (layout); other attributes are forwarded to <canvas>.
• Do not rely on onLoad to access the rive instance — use useEffect watching rive instead.
• Rive will not instantiate until <RiveComponent /> is rendered; the canvas must be present in the DOM.
• For conditional rendering patterns, lift useRive into an isolated wrapper component to avoid animation restarts caused by parent re-renders.

Related

• Overview
• useStateMachineInput
• Layout Props
• Data Binding

useStateMachineInput

Hook to retrieve a named input from an active state machine, enabling boolean, number, and trigger interactions from React code.

Deprecated — For new projects, prefer Data Binding with useViewModelInstance* hooks.

Signature / Usage

useStateMachineInput(
  rive: Rive | null,
  stateMachineName?: string,
  inputName?: string,
  initialValue?: number | boolean
): StateMachineInput | null

import { useRive, useStateMachineInput } from '@rive-app/react-webgl2';

export default function Example() {
  const { rive, RiveComponent } = useRive({
    src: 'my-animation.riv',
    stateMachines: 'State Machine 1',
    autoplay: true,
  });

  const hoverInput = useStateMachineInput(rive, 'State Machine 1', 'isHovered');
  const clickTrigger = useStateMachineInput(rive, 'State Machine 1', 'onClick');

  return (
    <RiveComponent
      onMouseEnter={() => hoverInput && (hoverInput.value = true)}
      onMouseLeave={() => hoverInput && (hoverInput.value = false)}
      onClick={() => clickTrigger && clickTrigger.fire()}
    />
  );
}

Options / Props

Parameters

StateMachineInput (return value)

Notes

• Returns null until the rive instance is loaded and the state machine is active.
• Use fire() for trigger-type inputs; set value for boolean or number inputs.
• useStateMachineInput is deprecated — new projects should use Data Binding hooks (useViewModelInstanceBoolean, useViewModelInstanceNumber, useViewModelInstanceTrigger, etc.).

Related

• useRive
• Data Binding

Audio

Playing audio from Rive animations in the web runtime.

Signature / Usage

import { Rive } from "@rive-app/webgl2";

const r = new Rive({
  src: "scene.riv",
  canvas: document.getElementById("canvas") as HTMLCanvasElement,
  autoplay: true,
  stateMachines: "Main",
});

// Adjust playback volume (0.0 = muted, 1.0 = full)
r.volume = 0.5;

Options / Props

volume property

r.volume: number  // getter / setter

Acts as a multiplier applied on top of each audio event's own volume setting from the editor.

Audio asset loading

Embedded audio plays automatically with no extra setup. For referenced audio assets, provide an assetLoader callback and check asset.isAudio:

assetLoader: (asset, bytes) => {
  if (asset.isAudio) {
    // load and assign audio bytes
    return true;
  }
  return false;
}

Notes

• Most browsers block audio playback until the user interacts with the page (click or touch). Audio will not play before that first interaction regardless of Rive configuration.
• Audio requires @rive-app/webgl2 or @rive-app/canvas; it is not supported in @rive-app/canvas-lite.
• Audio events are authored in the Rive editor and triggered via timelines, state transitions, or listeners.

Related

• loading-assets.md
• rive-constructor.md
• packages.md

Data Binding

Connect JavaScript code to animated properties through View Models and View Model Instances (VMI).

Signature / Usage

import { Rive } from "@rive-app/webgl2";

const r = new Rive({
  src: "scene.riv",
  canvas: document.getElementById("canvas") as HTMLCanvasElement,
  autoplay: true,
  autoBind: true,          // auto-bind default ViewModel with default instance
  stateMachines: "Main",
  onLoad: () => {
    const vmi = r.viewModelInstance;

    // Read / write properties
    vmi.boolean("isVisible").value = true;
    vmi.string("label").value = "Hello, Rive!";
    vmi.number("score").value = 42;
    vmi.trigger("onClick").trigger();

    // Observe changes
    vmi.number("score").on((event) => {
      console.log("score changed:", event.data);
    });
  },
});

Options / Props

Getting View Models from a Rive instance

Creating View Model Instances

Binding an instance

r.bindViewModelInstance(vmi);   // manual binding (autoBind: false)
// or
const vmi = r.viewModelInstance; // read bound instance (autoBind: true)

Property accessors on ViewModelInstance

ColorProperty helpers

const c = vmi.color("bgColor");
c.value = 0xFF000000;            // ARGB integer
c.rgb(255, 0, 0);                // RGB
c.rgba(255, 0, 0, 128);          // RGB + alpha
c.argb(128, 255, 0, 0);          // ARGB
c.opacity(0.5);                  // alpha only

Nested property path

// Chain
const n = vmi.viewModel("Card").number("rating");
// Path string (forward-slash delimited)
const n = vmi.number("Card/rating");

Observability

const prop = vmi.number("score");
prop.on((event) => console.log(event.data));   // subscribe
prop.off(callback);                             // remove specific listener
prop.off();                                     // remove all listeners

List property

const list = vmi.list("todos");
list.length;                          // number of items
list.addInstance(todoVMI);            // append
list.removeInstance(todoVMI);         // remove by reference
list.removeInstanceAt(0);             // remove by index
list.swap(0, 1);                      // swap two items

Image property

const img = vmi.image("avatar");
const decoded = await rive.decodeImage(new Uint8Array(await res.arrayBuffer()));
img.value = decoded;
decoded.unref();                      // release after setting
img.value = null;                     // clear

Artboard property (component swap)

const artboardProp = vmi.artboard("Character");
const assetsFile = new RiveFile({ src: "assets.riv", onLoad: () => {
  artboardProp.value = assetsFile.getBindableArtboard("Hero");
}});
assetsFile.init();

Notes

• Data Binding is the modern replacement for the legacy stateMachineInputs() API.
• Pass autoBind: true to automatically bind the default View Model with its default instance.
• Nested View Models can be accessed via method chaining or forward-slash path strings.
• Always call unref() on decoded image assets once assigned to free memory.

Related

• rive-constructor.md
• rive-methods.md
• state-machine-playback.md
• loading-assets.md

Events

Subscribe to Rive runtime lifecycle events and Rive-defined custom events from animations and state machines.

Signature / Usage

import { Rive, EventType, RiveEventType } from "@rive-app/webgl2";

const r = new Rive({
  src: "scene.riv",
  canvas: document.getElementById("canvas") as HTMLCanvasElement,
  autoplay: true,
  stateMachines: "Main",
});

// Subscribe to Rive events fired from the animation
r.on(EventType.RiveEvent, (event) => {
  const riveEvent = event.data;

  if (riveEvent.type === RiveEventType.OpenUrl) {
    // Handle URL event manually
    const anchor = document.createElement("a");
    anchor.href = riveEvent.properties.url;
    anchor.target = riveEvent.properties.target ?? "_blank";
    if (anchor.href) anchor.click();
  }

  if (riveEvent.type === RiveEventType.General) {
    console.log("General event:", riveEvent.name, riveEvent.properties);
  }
});

// Subscribe to lifecycle events
r.on(EventType.StateChange, (event) => {
  console.log("state changed to:", event.data);
});

// Unsubscribe
r.off(EventType.RiveEvent, myCallback);

Options / Props

on / off

r.on(type: EventType, callback: (event: Event) => void): void
r.off(type: EventType, callback: (event: Event) => void): void

EventType enum

RiveEventType enum (for EventType.RiveEvent payloads)

Event payload shape for EventType.RiveEvent

{
  data: {
    name: string;           // event name from the editor
    type: RiveEventType;    // General or OpenUrl
    properties: Record<string, unknown>;  // custom key/value pairs
    // OpenUrl-specific:
    properties.url?: string;
    properties.target?: string;  // e.g. "_blank"
  }
}

Lifecycle event payload

// StateChange
{ data: string[] }   // active state name(s)

// Play / Pause / Stop / Loop
{ data: string }     // animation or state machine name

Constructor callback shortcuts

The following constructor parameters are shorthand for on() calls:

Notes

• EventType.RiveEvent replaces the deprecated general Rive Events system; prefer Data Binding for state communication in new projects.
• OpenUrl events do not navigate automatically; you must implement the navigation logic in the callback.
• Setting automaticallyHandleEvents: true in the constructor makes the runtime open URLs for OpenUrl events without a manual callback.
• General (deprecated) events still fire via EventType.RiveEvent with type === RiveEventType.General.

Related

• rive-constructor.md
• rive-methods.md
• state-machine-playback.md
• data-binding.md

Fonts

Dynamic font loading and fallback font configuration for the Rive web runtime.

Signature / Usage

import { RiveFont, decodeFont, Rive } from "@rive-app/webgl2";

// Set fallback font callback BEFORE creating Rive instance
RiveFont.setFallbackFontCallback((codePoint, weight) => {
  // Return decoded font(s) for the given Unicode code point, or null
  if (codePoint >= 0x0E00 && codePoint <= 0x0E7F) {
    return [decodedThaiFont];
  }
  return null;
});

const r = new Rive({
  src: "scene.riv",
  canvas: document.getElementById("canvas") as HTMLCanvasElement,
  autoplay: true,
  assetLoader: async (asset, bytes) => {
    if (asset.isFont) {
      const res = await fetch("/fonts/custom.ttf");
      const font = await decodeFont(new Uint8Array(await res.arrayBuffer()));
      asset.setFont(font);
      font.unref();
      return true;
    }
    return false;
  },
});

Options / Props

Dynamic font loading via assetLoader

See loading-assets.md for the full assetLoader API. For fonts, the key steps are:

1. Fetch the font file as an ArrayBuffer 2. Decode with decodeFont(bytes: Uint8Array): Promise<Font> 3. Call asset.setFont(font) 4. Call font.unref() to release the reference

Fallback font API (v2.37.1+)

RiveFont.setFallbackFontCallback(
  (codePoint: number, weight: number) => Font[] | null
)

Returns an array of decoded Font objects to attempt in order, or null to skip fallback.

Notes

• Browsers block access to system fonts for security; fallback fonts must be explicitly decoded and provided.
• RiveFont.setFallbackFontCallback must be called before Rive initialization to take effect.
• The fallback callback may be invoked multiple times per missing glyph if successive fallback fonts also lack support.
• Fonts embedded in the .riv file are loaded automatically with no extra code.

Related

• loading-assets.md
• rive-constructor.md

Layout / Fit / Alignment

Controls how Rive content is scaled and positioned within the canvas.

Signature / Usage

import { Rive, Layout, Fit, Alignment } from "@rive-app/webgl2";

const r = new Rive({
  src: "vehicles.riv",
  canvas: document.getElementById("canvas") as HTMLCanvasElement,
  layout: new Layout({
    fit: Fit.Cover,
    alignment: Alignment.TopCenter,
  }),
  autoplay: true,
});

Options / Props

Layout constructor

new Layout(params?: LayoutParameters)

Fit enum values

Alignment enum values

Notes

• Alignment has no effect when fit is Fit.Layout.
• When providing explicit minX/minY/maxX/maxY bounds, they override alignment positioning.
• Call r.resizeToCanvas() after canvas resize to update the layout bounds.

Related

• rive-constructor.md
• packages.md

Loading Assets

Three strategies for supplying image, font, and audio assets to a Rive file at runtime.

Signature / Usage

import { Rive, decodeFont, decodeImage } from "@rive-app/webgl2";

const r = new Rive({
  src: "scene.riv",
  canvas: document.getElementById("canvas") as HTMLCanvasElement,
  autoplay: true,
  assetLoader: async (asset, bytes) => {
    if (asset.isFont) {
      const response = await fetch("/fonts/custom.ttf");
      const font = await decodeFont(new Uint8Array(await response.arrayBuffer()));
      asset.setFont(font);
      font.unref();
      return true;   // we handled it
    }
    if (asset.isImage) {
      const response = await fetch("/images/hero.png");
      const image = await decodeImage(new Uint8Array(await response.arrayBuffer()));
      asset.setImage(image);
      image.unref();
      return true;
    }
    return false;    // let runtime handle it
  },
});

Options / Props

Asset loading strategies

assetLoader callback

assetLoader: (asset: FileAsset, bytes: Uint8Array) => boolean

Called for every asset the runtime detects in the .riv file on load.

Return true if your code handled the asset; false to let the runtime handle it.

FileAsset properties and methods

Decode helpers

Supported image formats

JPEG, PNG, WebP.

Notes

• Always call asset.unref() (or font.unref() / image.unref()) after assigning the decoded asset to allow garbage collection.
• enableRiveAssetCDN: false disables automatic CDN fetching when you want full control over all asset loading.
• For Data Binding image properties, use decodeImage and assign via vmi.image("name").value = decoded — see data-binding.md.

Related

• rive-constructor.md
• fonts.md
• audio.md
• data-binding.md

Web Packages Overview

Three npm packages for different rendering needs and bundle-size trade-offs.

Signature / Usage

npm install @rive-app/webgl2
# or
npm install @rive-app/canvas
# or
npm install @rive-app/canvas-lite

<!-- Via CDN (no bundler) -->
<script src="https://unpkg.com/@rive-app/webgl2"></script>

import { Rive } from "@rive-app/webgl2";
// or selective import
import * as rive from "@rive-app/webgl2";

Options / Props

Notes

• @rive-app/webgl2 is the recommended default — best rendering quality and performance for most use cases.
• Choose @rive-app/canvas when WebGL2 is unavailable or simpler graphics are targeted.
• Choose @rive-app/canvas-lite only when bundle size is the top priority and text, layouts, audio, and scripting features are not needed.
• When rendering many Rive instances on one page with WebGL2, set useOffscreenRenderer: true to avoid hitting the browser's WebGL context limit.
• The legacy @rive-app/webgl package is deprecated (no updates after v2.37.0).

Related

• rive-constructor.md
• layout.md

Preloading WASM

Self-host and preload the Rive WebAssembly binary for faster startup and better reliability.

Signature / Usage

import riveWASMResource from "@rive-app/webgl2/rive.wasm";
import { Rive, RuntimeLoader } from "@rive-app/webgl2";

// Call before creating any Rive instance
RuntimeLoader.setWasmUrl(riveWASMResource);

const r = new Rive({
  src: "scene.riv",
  canvas: document.getElementById("canvas") as HTMLCanvasElement,
  autoplay: true,
});

Options / Props

RuntimeLoader.setWasmUrl(url: string): void

RuntimeLoader is a singleton; call setWasmUrl once per page, before any Rive instance is created.

Notes

• By default the runtime fetches rive.wasm from the Rive CDN on first use.
• Preloading avoids the CDN dependency and speeds up time-to-first-frame.
• Your bundler (Vite, webpack, etc.) may require configuration to import .wasm files as data URIs.
• The WASM version must match the installed @rive-app/* package version.

Related

• rive-constructor.md
• packages.md

runtimes-web

Rive (constructor)

High-level class that loads a .riv file, manages the render loop, and exposes playback controls.

Signature / Usage

const r = new Rive(params: RiveParameters): Rive

import { Rive } from "@rive-app/webgl2";

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

Options / Props

File source (one required)

Rendering

Playback

Asset loading

Interaction

Lifecycle callbacks

Notes

• Call r.resizeDrawingSurfaceToCanvas() inside onLoad to match the canvas's device pixel ratio.
• Call r.cleanup() when the instance is no longer needed to free WASM memory.
• Only one artboard can be rendered per Rive instance.

Related

• packages.md
• layout.md
• state-machine-playback.md
• data-binding.md
• loading-assets.md
• rive-methods.md

RiveFile

Pre-parse a .riv file once and share it across multiple Rive instances to avoid redundant loading and parsing.

Signature / Usage

import { Rive, RiveFile } from "@rive-app/webgl2";

const file = new RiveFile({
  src: "vehicles.riv",
  onLoad: () => {
    // File is parsed and ready — create instances
    const r1 = new Rive({
      riveFile: file,
      canvas: document.getElementById("canvas1") as HTMLCanvasElement,
      stateMachines: "Motion",
      autoplay: true,
    });

    const r2 = new Rive({
      riveFile: file,
      canvas: document.getElementById("canvas2") as HTMLCanvasElement,
      stateMachines: "Motion",
      autoplay: true,
    });
  },
  onLoadError: (err) => console.error(err),
});
file.init();

Options / Props

RiveFile constructor

View Model access from RiveFile

Notes

• file.init() must be called after constructing RiveFile to begin loading.
• Each Rive instance receives independent playback state even when sharing the same RiveFile.
• Useful when the same .riv file is used in multiple locations on the same page (e.g., a list of animated cards).

Related

• rive-constructor.md
• data-binding.md

Rive Instance Methods

Methods available on a Rive instance for playback control, rendering, data access, and resource management.

Signature / Usage

const r = new Rive({ ... });

// Playback
r.play("animationName");
r.pause();
r.stop();
r.reset({ stateMachines: "Machine", autoplay: true });

// Rendering
r.resizeDrawingSurfaceToCanvas();
r.startRendering();
r.stopRendering();

// Cleanup
r.cleanup();

Options / Props

Playback control

Rendering

State machine inputs

Data / state accessors

View Model

Events

Cleanup

Notes

• stateMachineInputs(name) is the legacy approach for controlling state machines; prefer Data Binding for new projects.
• reset() recreates instances from scratch; any bound ViewModelInstance must be rebound afterward.
• Always call cleanup() when removing a Rive component to prevent WASM memory leaks.

Related

• rive-constructor.md
• state-machine-playback.md
• data-binding.md
• events.md

State Machine Playback

Control state machine playback and interact with inputs (booleans, numbers, triggers) from JavaScript.

Signature / Usage

import { Rive, StateMachineInputType } from "@rive-app/webgl2";

const r = new Rive({
  src: "interactive.riv",
  canvas: document.getElementById("canvas") as HTMLCanvasElement,
  autoplay: true,
  stateMachines: "MainMachine",
  onLoad: () => {
    r.resizeDrawingSurfaceToCanvas();

    const inputs = r.stateMachineInputs("MainMachine");
    const boolInput  = inputs.find((i) => i.name === "isHovered");
    const numInput   = inputs.find((i) => i.name === "progress");
    const trigInput  = inputs.find((i) => i.name === "clicked");

    // Boolean
    boolInput.value = true;
    // Number
    numInput.value = 0.75;
    // Trigger
    trigInput.fire();
  },
  onStateChange: (event) => {
    console.log("current state(s):", event.data);
  },
});

Options / Props

Playback methods

stateMachineInputs(name: string): StateMachineInput[]

Returns an array of input objects for the named state machine.

StateMachineInput

StateMachineInputType enum

onStateChange callback

Fires whenever the state machine transitions to a new state.

onStateChange: (event: { data: string[] }) => void

event.data contains the name(s) of the current active state(s).

Notes

• The stateMachineInputs() approach is the legacy way of controlling state machines; for new projects, prefer Data Binding.
• State machines may "settle" (stop advancing) when no further state changes will occur — this is a performance optimization.
• Multiple state machine names can be passed to the constructor: stateMachines: ["Machine1", "Machine2"].

Related

• rive-constructor.md
• rive-methods.md
• data-binding.md
• events.md

React Interactive

Use @rive-app/react-canvas with useRive and useStateMachineInput to build an interactive animation that responds to user events.

import { useRive, useStateMachineInput } from "@rive-app/react-canvas";

export default function InteractiveButton() {
  const { rive, RiveComponent } = useRive({
    src: "button.riv",
    stateMachines: "Button State",
    autoplay: true,
  });

  const isHoverInput = useStateMachineInput(rive, "Button State", "isHover");

  const onMouseEnter = () => {
    if (isHoverInput) isHoverInput.value = true;
  };

  const onMouseLeave = () => {
    if (isHoverInput) isHoverInput.value = false;
  };

  return (
    <div onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
      <RiveComponent />
    </div>
  );
}

Notes

• useRive が返す RiveComponent をそのまま JSX に配置すると、canvas のマウント・リサイズ・クリーンアップが自動で管理される
• useStateMachineInput は rive が準備完了するまで null を返す。操作前に null チェックが必要
• rive.play() / rive.pause() を RiveComponent の onMouseEnter / onMouseLeave に直接渡すことで再生制御も可能
• useDevicePixelRatio（デフォルト true）により HiDPI 環境での鮮明なレンダリングが自動で有効になる

samples

State Machine Control

Control State Machine inputs (boolean / number / trigger) from code using the web JS runtime.

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

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

    // Retrieve all inputs for a named state machine
    const inputs = r.stateMachineInputs("bumpy");

    // Trigger input — fires a one-shot transition
    const bumpTrigger = inputs.find((i) => i.name === "bump");
    bumpTrigger.fire();

    // Number input — set an arbitrary numeric value
    const levelInput = inputs.find((i) => i.name === "level");
    levelInput.value = 42;

    // Boolean input — toggle a state
    const isActiveInput = inputs.find((i) => i.name === "isActive");
    isActiveInput.value = true;
  },
});

// Monitor state changes
r.on("statechange", (event) => {
  console.log("current state:", event.data[0]);
});

Notes

• stateMachineInputs(name) は State Machine がロードされた後（onLoad 以降）に呼び出す
• Trigger は .fire() で発火し、状態遷移を一度だけ起こす。Number/Boolean は .value プロパティへの代入で制御する
• 入力名は Rive エディター上で設定した名前と一致させる必要がある（大文字・小文字を区別する）
• statechange イベントで現在のステート名を取得でき、UI との同期やデバッグに使用する

Web Basic Setup

Load a .riv file onto a canvas element using @rive-app/canvas with minimal configuration and cleanup.

<!-- index.html -->
<canvas id="canvas" width="500" height="500"></canvas>

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

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

// Cleanup when no longer needed
r.cleanup();

Notes

• resizeDrawingSurfaceToCanvas() は onLoad コールバック内で呼び出し、デバイスピクセル比に合わせてレンダリングを鮮明にする
• stateMachines に State Machine 名を渡すと、State Machine が起動した状態でアニメーションが開始される
• autoplay: true を省略するとアニメーションは停止状態で読み込まれる
• r.cleanup() でメモリリソースを解放する。コンポーネントのアンマウント時・ページ離脱時に呼び出す

Install

各 Rive ランタイムパッケージのインストールコマンド。

Web ランタイム（推奨: WebGL2）

Rive Renderer を使用するフル機能パッケージ。Vector Feathering・Rive Text・スクリプティング等の高度な機能を利用できる。

npm install @rive-app/webgl2

yarn add @rive-app/webgl2

pnpm add @rive-app/webgl2

bun add @rive-app/webgl2

Web ランタイム（Canvas）

Rive Renderer を使わない Canvas 2D ベースのパッケージ。高度な機能は利用不可。

npm install @rive-app/canvas

yarn add @rive-app/canvas

pnpm add @rive-app/canvas

Web ランタイム（Canvas Lite）

Canvas ベースの軽量パッケージ。テキスト・レイアウト・スクリプティング・オーディオ機能が不要な場合に使用する。

npm install @rive-app/canvas-lite

yarn add @rive-app/canvas-lite

pnpm add @rive-app/canvas-lite

React ランタイム（推奨: WebGL2）

@rive-app/webgl2 をラップする React 向けパッケージ。フル機能利用時に推奨。

npm install --save @rive-app/react-webgl2

yarn add @rive-app/react-webgl2

pnpm add @rive-app/react-webgl2

React ランタイム（Canvas）

@rive-app/canvas をラップする React 向けパッケージ。

npm install --save @rive-app/react-canvas

yarn add @rive-app/react-canvas

pnpm add @rive-app/react-canvas

React ランタイム（Canvas Lite）

バンドルサイズを最小化したい場合の React 向けパッケージ。Rive Text 等の高度な機能は利用不可。

npm install --save @rive-app/react-canvas-lite

yarn add @rive-app/react-canvas-lite

pnpm add @rive-app/react-canvas-lite

CDN 経由での読み込み（WebGL2 — 最新版）

HTML に直接 <script> タグで読み込む場合。ビルドツールを使わない環境向け。

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

CDN 経由での読み込み（WebGL2 — バージョン固定）

本番環境ではバージョンを固定することを推奨する。

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

バージョン番号は npm で最新版を確認して置き換える（npm show @rive-app/webgl2 version）。

scripts