Runtimes Quick Start
The Rive runtimes are open-source libraries that allow you to load and control your animations in apps, games, and websites.
Web
React
Vue
Flutter
iOS
Android
React Native
Angular

1. Add the Rive library

Add a script tag to a web page:
1
<script src="https://unpkg.com/@rive-app/[email protected]"></script>
Copied!
Alternatively, you can import our recommended web runtime package via NPM in your project:
1
npm install @rive-app/canvas
2
3
// example.js
4
import rive from "@rive-app/canvas";
Copied!
If you need more details and options for a web runtime, checkout 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:
1
<canvas id="canvas" width="500" height="500"></canvas>
Copied!

3. Create a Rive object

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 a local .riv file
  • canvas - The canvas element on which you want the animation to render
  • autoplay - Boolean for whether you want the default animation to play
1
<script>
2
new rive.Rive({
3
src: "https://cdn.rive.app/animations/vehicles.riv",
4
// Or the path to a local Rive asset
5
// src: './example.riv',
6
canvas: document.getElementById("canvas"),
7
autoplay: true
8
});
9
</script>
Copied!

Complete example

Putting this altogether, you can load this example Rive animation in one HTML file:
1
<html>
2
<head>
3
<title>Rive Hello World</title>
4
</head>
5
<body>
6
<canvas id="canvas" width="500" height="500"></canvas>
7
8
<script src="https://unpkg.com/@rive-app/[email protected]"></script>
9
<script>
10
new rive.Rive({
11
src: "https://cdn.rive.app/animations/vehicles.riv",
12
canvas: document.getElementById("canvas"),
13
autoplay: true
14
});
15
</script>
16
</body>
17
</html>
Copied!
Try it out on your own: Check out this CodeSandbox for a small setup to test your own Rive files in!
API Docs: Check out the web runtime README docs for more on what you can do with the Rive API.

Install the rive-react package

The Rive React runtime allows for 2 main options based on which backing renderer you need.
  • (Recommended) @rive-app/react-canvas - Wraps the @rive-app/canvas dependency. Unless you specifically need a WebGL backing renderer, we recommend you use this dependency when using Rive in your apps for quick and fast usage.
  • @rive-app/react-webgl - Wraps the @rive-app/webgl dependency. In the future, we may have advanced rendering features that are only supported by using WebGL . We are currently working on improving the performance with this backing renderer.
1
npm i --save @rive-app/react-canvas
Copied!
Before v2.0.0, the React runtime was powered by the rive-react dependency and is still published today. Despite being actively published, It contains a larger bundle, as it has dependencies for both @rive-app/canvas and @rive-app/webgl . Starting in v2.0.0, we recommend you switch to one of the above dependencies instead.

Component

Rive React provides a basic component as its default import for displaying simple animations.
1
import Rive from '@rive-app/react-canvas'
2
3
export const Simple = () => (
4
<Rive src="https://cdn.rive.app/animations/vehicles.riv" />
5
);
Copied!

Props

  • src: File path or URL to the .riv file to display.
  • artboard: (optional) Name to display.
  • animations: (optional) Name or list of names of animations to play.
  • layout: (optional) Layout object to define how animations are displayed on the canvas.
  • All attributes and event handlers that can be passed to a div element can also be passed to the Rive component and used in the same manner.

useRive Hook

For more advanced usage, the useRive hook is provided. The hook will return a component and a Rive object which gives you control of the current rive file.
1
import { useRive } from '@rive-app/react-canvas';
2
3
export default function Simple() {
4
const { rive, RiveComponent } = useRive({
5
src: 'https://cdn.rive.app/animations/vehicles.riv',
6
autoplay: false,
7
});
8
9
return (
10
<RiveComponent
11
onMouseEnter={() => rive && rive.play()}
12
onMouseLeave={() => rive && rive.pause()}
13
/>
14
);
15
}
Copied!

Parameters

  • riveParams: Set of parameters that are passed to the Rive.js Rive class constructor. null and undefined can be passed to conditionally display the .riv file.
  • opts: Rive React-specific options.

Return Values

  • RiveComponent: A Component that can be used to display your .riv file. This component accepts the same attributes and event handlers as a div element.
  • rive: A Rive.js Rive object. This will return as null until the .riv file has fully loaded.
  • canvas: HTMLCanvasElement object, on which the .riv file is rendering.
  • setCanvasRef: A callback ref that can be passed to your own canvas element, if you wish to have control over the rendering of the Canvas element.
  • setContainerRef: A callback ref that can be passed to a container element that wraps the canvas element, if you wish to have control over the rendering of the container element.
    For the vast majority of use cases, you can just the returned RiveComponent and don't need to worry about setCanvasRef and setContainerRef.

riveParams

  • src?: (optional) File path or URL to the .riv file to use. One of src or buffer must be provided.
  • 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.
  • stateMachines?: (optional) Name or list of names of state machines to load.
  • layout?: (optional) Layout object to define how animations are displayed on the canvas. See our web runtime docs for more details.
  • autoplay?: (optional) If true, the animation will automatically start playing when loaded. Defaults to false.
  • onLoad?: (optional) Callback that gets fired when the .rive 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.

opts

  • useDevicePixelRatio: (optional) If true, the hook will scale the resolution of the animation based on the devicePixelRatio. Defaults to true. NOTE: Requires the setContainerRef ref callback to be passed to an element wrapping a canvas element. If you use the RiveComponent, then this will happen automatically.
  • fitCanvasToArtboardHeight: (optional) If true, then the canvas will resize based on the height of the artboard. Defaults to false.
The following snippet demonstrates how to create a simple Rive component in Vue 2.
1
<template>
2
<div>
3
<canvas ref="canvas" width="400" height="400"></canvas>
4
</div>
5
</template>
6
7
<script>
8
import { Rive, Layout } from '@rive-app/canvas';
9
10
export default {
11
name: 'Rive',
12
props: {
13
src: String,
14
fit: String,
15
alignment: String
16
},
17
mounted() {
18
new Rive({
19
canvas: this.$refs.canvas,
20
src: this.$props.src,
21
layout: new Layout({
22
fit: this.$props.fit,
23
alignment: this.$props.alignment,
24
}),
25
autoplay: true
26
})
27
}
28
}
29
</script>
Copied!

1. Add the Rive package dependency

pubspec.yaml
1
dependencies:
2
rive:
Copied!

2. Import the Rive package

1
import 'package:rive/rive.dart';
Copied!

3. Add a RiveAnimation widget

1
RiveAnimation.network(
2
'https://cdn.rive.app/animations/vehicles.riv',
3
)
Copied!

Complete example

main.dart
1
import 'package:flutter/material.dart';
2
import 'package:rive/rive.dart';
3
4
void main() => runApp(MaterialApp(
5
home: MyRiveAnimation(),
6
));
7
8
class MyRiveAnimation extends StatelessWidget {
9
@override
10
Widget build(BuildContext context) {
11
return const Scaffold(
12
body: Center(
13
child: RiveAnimation.network(
14
'https://cdn.rive.app/animations/vehicles.riv',
15
fit: BoxFit.cover,
16
),
17
),
18
);
19
}
20
}
Copied!

1a. Add Rive via Cocoapods

Add the following to your Podspec file:
Podfile
1
pod 'RiveRuntime'
Copied!

1b. Add Rive via Swift Package Manager

To install via Swift Package Manager, in the package finder in xcode, search with the Github repository name: https://github.com/rive-app/rive-ios

2. Importing Rive

Add the following to the top of your file where you utilize the Rive runtime:
1
import RiveRuntime
Copied!

3. v2 Runtime Usage

Rive iOS runtimes of versions 2.x.x or later should use the newer patterns for integrating Rive into your iOS applications. This involves some API changes from the pattern in versions 1.x.x.

3a. UIKit

Set up RiveViewModel w/ Controller

The simplest way of adding Rive to a controller is to make a RiveViewModel and set its view as the RiveView when it is loaded.
1
class SimpleAnimationViewController: UIViewController {
2
@IBOutlet weak var rview: RiveView!
3
// Load the truck_v7 resource assets
4
var rSimpleVM: RiveViewModel = RiveModel(fileName: "truck_v7")
5
// or choose to load the Rive file in from a URL
6
// var rSimpleVM: RiveViewModel = RiveModel(webURL: "https://cdn.rive.app/animations/vehicles.riv")
7
8
override public func viewDidLoad() {
9
super.viewDidLoad()
10
rSimpleVM.setView(rview)
11
}
12
}
Copied!

3b. SwiftUI

Set up RiveViewModel

1
struct SwiftSimpleAnimation: DismissableView {
2
var dismiss: () -> Void = {}
3
4
var body: some View {
5
RiveViewModel(fileName: "truck").view()
6
}
7
}
Copied!

4. v1 Runtime Usage

For UIKit usage, follow the quickstart guidelines below -

4a. Create a UIViewController

If you're using UIKit, a simple way to get started is to start by creating a UIViewController:
1
import UIKit
2
import RiveRuntime
3
4
class RiveViewController: UIViewController {
5
6
override public func loadView() {
7
super.loadView()
8
}
9
}
Copied!

4b. Add a RiveView and a RiveFile

Next, you can instantiate a RiveView and use the RiveFile API to load in this example .riv asset. Then simply set the RiveView as the controller's view when loaded:
1
import UIKit
2
import RiveRuntime
3
4
class RiveViewController: UIViewController {
5
let url = "https://cdn.rive.app/animations/vehicles.riv"
6
7
override public func loadView() {
8
super.loadView()
9
10
let view = RiveView()
11
guard let riveFile = RiveFile(httpUrl: url, with: view) else {
12
fatalError("Unable to load RiveFile")
13
}
14
15
view.configure(riveFile)
16
self.view = view
17
}
18
}
Copied!

4c. Tidy up once the view is dismissed

1
override public func viewDidDisappear(_ animated: Bool) {
2
(view as! RiveView).stop()
3
super.viewDidDisappear(animated)
4
}
Copied!

1. Add the Rive dependency

Add the following dependencies to your build.gradle file in your project:
1
dependencies {
2
implementation 'app.rive:rive-android:2.0.19'
3
// During initialization, you may need to add a dependency
4
// for Jetpack Startup
5
implementation "androidx.startup:startup-runtime:1.1.0"
6
}
Copied!

2. Initialize Rive

Rive needs to initialize its runtime when your app starts.
It can be done via an initializer that does this for you automatically. The initialization provider can be set up directly in your app's manifest file:
1
<provider
2
android:name="androidx.startup.InitializationProvider"
3
android:authorities="${applicationId}.androidx-startup"
4
android:exported="false"
5
tools:node="merge">
6
<meta-data android:name="app.rive.runtime.kotlin.RiveInitializer"
7
android:value="androidx.startup" />
8
</provider>
Copied!
Otherwise, this can be achieved by calling the initializer in code:
1
AppInitializer.getInstance(applicationContext)
2
.initializeComponent(RiveInitializer::class.java)
Copied!
If you want to initialize Rive yourself, this can be done in code:
1
Rive.init(context)
Copied!

3. Add RiveAnimation to your layout

The simplest way to get a Rive animation into your application is to include it as part of a layout. The following will consist of the Rive file loaded from the raw resources and auto-play its first animation. This assumes you have taken a downloaded .riv file (i.e off_road_car_blog.riv) and placed it in your raw resources folder.
simple.xml
1
<app.rive.runtime.kotlin.RiveAnimationView
2
android:layout_width="match_parent"
3
android:layout_height="match_parent"
4
app:riveResource="@raw/off_road_car_blog" />
5
Copied!
Another way to load a Rive file in is by referencing the URL where the asset lives (see Internet Permissions section below for an extra step in setup):
simple.xml
1
<app.rive.runtime.kotlin.RiveAnimationView
2
android:layout_width="match_parent"
3
android:layout_height="match_parent"
4
app:riveUrl="https://cdn.rive.app/animations/vehicles.riv" />
Copied!
When setting your context views, this might look like
1
import android.os.Bundle
2
import androidx.appcompat.app.AppCompatActivity
3
4
class SimpleActivity : AppCompatActivity() {
5
6
override fun onCreate(savedInstanceState: Bundle?) {
7
super.onCreate(savedInstanceState)
8
setContentView(R.layout.simple)
9
}
10
}
Copied!

Internet permissions

If you're retrieving Rive files over a network, your app will need permission to access the internet:
AndroidManifest.xml
1
<uses-permission android:name="android.permission.INTERNET" />
2
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Copied!
Note that this isn't necessary if you include the files in your Android project and load these in as a raw resource.

Resources

1. Add the Rive dependency

1
npm install --save rive-react-native
Copied!

2. Create iOS bridging header

  • open the iOS project file in XCode open ios/<name>.xcodeproj
  • create a new empty swift file.
  • confirm "Create Bridging Header"

3. Add your rive component

App.js
1
import Rive from 'rive-react-native';
2
3
function App() {
4
return <Rive
5
url="https://cdn.rive.app/animations/vehicles.riv"
6
style={{width: 400, height: 400}}
7
/>;
8
}
Copied!

1. Install :

1
npm install ng-rive
Copied!

2. Import RiveModule:

animation.module.ts
1
import { RiveModule } from 'ng-rive';
2
3
@NgModule({
4
declarations: [AnimationComponent],
5
imports: [
6
CommonModule,
7
RiveModule,
8
],
9
})
10
export class AnimationModule { }
Copied!

3. Add your .riv file in your assets

1
|-- assets
2
| |--rive
3
| |-- vehicles.riv
Copied!

4. Use in template :

animation.component.html
1
<canvas riv="vehicles" width="500" height="500">
2
<riv-animation name="idle" play></riv-animation>
3
</canvas>
Copied!
Copy link