Skip to content

Latest commit

 

History

History
477 lines (347 loc) · 11.8 KB

quick-start.md

File metadata and controls

477 lines (347 loc) · 11.8 KB
description
The Rive runtimes are open-source libraries that allow you to load and control your animations in apps, games, and websites.

Runtimes Quick Start

{% tabs %} {% tab title="Web" %}

1. Add the Rive library

Add a script tag to a web page:

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

Alternatively, you can import our recommended web runtime package via NPM in your project:

npm install @rive-app/webgl

// example.js
import rive from "@rive-app/webgl";

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:

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

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
<script>
  new rive.Rive({
    src: "https://cdn.rive.app/animations/vehicles.riv",
    // Or the path to a local Rive asset
    // src: './example.riv',
    canvas: document.getElementById("canvas"),
    autoplay: true
  });
</script>

Complete example

Putting this altogether, you can load this example Rive animation in one HTML file:

<html>
  <head>
    <title>Rive Hello World</title>
  </head>
  <body>
    <canvas id="canvas" width="500" height="500"></canvas>

    <script src="https://unpkg.com/@rive-app/webgl"></script>
    <script>
      new rive.Rive({
        src: "https://cdn.rive.app/animations/vehicles.riv",
        canvas: document.getElementById("canvas"),
        autoplay: true
      });
    </script>
  </body>
</html>

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.

{% endtab %}

{% tab title="React" %}

Install the rive-react package

{% code title="" %}

npm i --save rive-react

{% endcode %}

Component

Rive React provides a basic component as it's default import for displaying simple animations.

import Rive from "rive-react";

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

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 animtions to play.
  • layout: (optional) Layout object to define how animations are displayed on the canvas.
  • All attributes and eventHandlers 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.

import { useRive } from "rive-react";

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

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

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 which 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 of list of names of state machines to load.
  • layout?: (optional) Layout object to define how animations are displayed on the canvas. See 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 get's fired when the .rive file loads .
  • onLoadError?: (optional) Callback that get's fired when an error occurs loading the .riv file.
  • onPlay?: (optional) Callback that get's fired when the animation starts playing.
  • onPause?: (optional) Callback that get's fired when the animation pauses.
  • onStop?: (optional) Callback that get's fired when the animation stops playing.
  • onLoop?: (optional) Callback that get's fired when the animation completes a loop.
  • onStateChange?: (optional) Callback that get's fired when a state change occurs.

opts

  • useDevicePixelRatio: (optional) If true, the hook will scale the resolution of the animation based the devicePixelRatio. Defaults to true. NOTE: Requires the setContainerRef ref callback to be passed to a 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. {% endtab %}

{% tab title="Vue" %} The following snippet demonstrates how to create a simple Rive component in Vue 2.

<template>
  <div>
    <canvas ref="canvas" width="400" height="400"></canvas>
  </div>
</template>

<script>
import { Rive, Layout } from '@rive-app/webgl';

export default {
  name: 'Rive',
  props: {
    src: String,
    fit: String,
    alignment: String
  },
  mounted() {
    new Rive({
        canvas: this.$refs.canvas,
        src: this.$props.src,
        layout: new Layout({
            fit: this.$props.fit,
            alignment: this.$props.alignment,
        }),
        autoplay: true
    })
  }
}
</script>

{% endtab %}

{% tab title="Flutter" %}

1. Add the Rive package dependency

{% code title="pubspec.yaml" %}

dependencies:
  rive:

{% endcode %}

2. Import the Rive package

import 'package:rive/rive.dart';

3. Add a RiveAnimation widget

RiveAnimation.network(
  'https://cdn.rive.app/animations/vehicles.riv',
)

Complete example

{% code title="main.dart" %}

import 'package:flutter/material.dart';
import 'package:rive/rive.dart';

void main() => runApp(MaterialApp(
      home: MyRiveAnimation(),
    ));

class MyRiveAnimation extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(
        child: RiveAnimation.network(
          'https://cdn.rive.app/animations/vehicles.riv',
          fit: BoxFit.cover,
        ),
      ),
    );
  }
}

{% endcode %} {% endtab %}

{% tab title="iOS" %}

1. Add the CocoaPods dependency

{% code title="Podfile" %}

  pod 'RiveRuntime', :git => 'git@github.com:rive-app/test-ios.git'

{% endcode %}

2. Create a UIViewController and import runtime

import UIKit
import RiveRuntime

class RiveViewController: UIViewController {

    override public func loadView() {
        super.loadView()
    }
}

3. Add a RiveView and a RiveFile

import UIKit
import RiveRuntime

class RiveViewController: UIViewController {
    let url = "https://cdn.rive.app/animations/vehicles.riv"

    override public func loadView() {
        super.loadView()

        let view = RiveView()
        guard let riveFile = RiveFile(httpUrl: url, with: view) else {
            fatalError("Unable to load RiveFile")
        }

        view.configure(riveFile)
        self.view = view
    }
}

4. Tidy up once the view is dismissed

override public func viewDidDisappear(_ animated: Bool) {
    (view as! RiveView).stop()
    super.viewDidDisappear(animated)
}

{% endtab %}

{% tab title="Android" %}

1. Add the Rive dependency

dependencies {
    implementation 'app.rive:rive-android:0.1.1'
}

2. Add RiveAnimation to your layout

    <app.rive.runtime.kotlin.RiveAnimationView
        android:id="@+id/my_rive_animation"

        android:layout_width="match_parent"
        android:layout_height="match_parent"

        app:riveUrl="https://cdn.rive.app/animations/vehicles.riv"
        app:riveFit="COVER" />

3. Clean up when done

{% code title="MyRiveActivity.kt" %}

class MyRiveActivity : AppCompatActivity() {

    private val animationView by lazy(LazyThreadSafetyMode.NONE) {
        findViewById<RiveAnimationView>(R.id.my_rive_animation)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.my_rive)
    }

    override fun onDestroy() {
        super.onDestroy()
        animationView.destroy()
    }
}

{% endcode %}

Internet permissions

This example requires your app to have permission to access the internet:

{% code title="AndroidManifest.xml" %}

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

{% endcode %}

This is needed only if you're retrieving Rive files over a network. If you include the files in your Android project, this isn't necessary. {% endtab %}

{% tab title="React Native" %}

1. Add the Rive dependency

npm install --save rive-react-native

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

{% code title="App.js" %}

import Rive from "rive-react-native";

function App() {
  return (
    <Rive
      url="https://cdn.rive.app/animations/vehicles.riv"
      style={{ width: 400, height: 400 }}
    />
  );
}

{% endcode %} {% endtab %}

{% tab title="Angular" %}

1. Install :

npm install ng-rive

2. Import RiveModule:

{% code title="animation.module.ts" %}

import { RiveModule } from "ng-rive";

@NgModule({
  declarations: [AnimationComponent],
  imports: [CommonModule, RiveModule]
})
export class AnimationModule {}

{% endcode %}

3. Add your .riv file in your assets

|-- assets
|   |--rive
|      |-- vehicles.riv

4. Use in template :

{% code title="animation.component.html" %}

<canvas riv="vehicles" width="500" height="500">
  <riv-animation name="idle" play></riv-animation>
</canvas>

{% endcode %} {% endtab %} {% endtabs %}