<!-- RiveTestHook.stories.mdx -->

import { useState } from 'react';

import { Canvas, Meta, Story, ArgsTable } from '@storybook/addon-docs';

import RiveComponent, { useRive, useStateMachineInput } from '../../src';
import { Button } from './components/Button';
import './rive-overview.css';

<Meta title="React Runtime/Overview" />

# Rive React Runtime

This is an examples/docs page for the official React runtime for Rive. Check out the various pages for how to use this SDK to incorporate Rive into your React-based web applications.

Want to follow along with these examples? Check out the `examples/` folder in the [rive-react](https://github.com/rive-app/rive-react) project to find all these examples and `.riv` assets you can inspect in the Rive editor by dragging and dropping them into your Rive editor file browser.

## What is Rive?

<img className="rive-logo" src="rive_logo_black_2x.png" alt="Rive logo" />

[Rive](https://rive.app/) is a real-time interactive design and animation tool. Use our collaborative editor to create motion graphics that respond to different states and user inputs. Then load your animations into apps, games, and websites with our lightweight open-source runtimes.

## How to use Rive at runtime

There's multiple ways to render Rive using the React runtime. See the associated code snippets that follow each example.

### Rive component

```tsx
import RiveComponent from '@rive-app/react-canvas';
```

The React runtime exports a default React component you can insert as JSX. Under the hood, it renders a `<canvas>` element that runs the animation, and a wrapping `<div>` element that handles sizing of the canvas based on the parent that wraps the component.

**When to use this**: Use this for simple rendering cases where you don't need to control playback or setup state machine inputs to advance state machines. It will simply autoplay the first animation it finds in the `.riv`, the animation name you provide it, or the state machine name if you provide one.

**Note:** Style-specific props set onto the component will pass down to the wrapping `<div>` element, while most other props will be set onto the `<canvas>` element itself.

<Canvas withSource="open">
  <Story name="Rive Component">
    {() => (
      <div className="center">
        <RiveComponent src="poison-loader.riv" className="base-canvas-size" />
      </div>
    )}
  </Story>
</Canvas>

#### Props

In addition to the props laid out below, the component accepts other props that can be set on the `<canvas>` element.

<ArgsTable of={RiveComponent} />

### useRive Hook

```tsx
import { useRive } from '@rive-app/react-canvas';
```

The runtime also exports a named `useRive` hook that allows for more control at Rive instantiation, since it passes back a `rive` object you can use to manipulate state machines, control playback, and more.

**When to use this:** When you need to control your Rive animation in any aspect, such as controlling playback, using state machine inputs to advance state machines, add adding callbacks on certain Rive-specific events such as `onStateChange`, `onPause`, etc.

<Canvas withSource="open">
  <Story name="useRive Hook">
    {() => {
      const [isPlaying, setIsPlaying] = useState(true);
      const [animationText, setAnimationText] = useState('');
      const { rive, RiveComponent: RiveComponentPlayback } = useRive({
        src: 'truck.riv',
        stateMachines: 'drive',
        artboard: 'Truck',
        autoplay: true,
        onPause: () => {
          setAnimationText('Animation paused!');
        },
        onPlay: () => {
          setAnimationText('Animation is playing..');
        },
      });
      const togglePlaying = () => {
        if (isPlaying) {
          rive.pause();
          setIsPlaying(false);
        } else {
          rive.play();
          setIsPlaying(true);
        }
      };
      return (
        <>
          <div className="center">
            <RiveComponentPlayback className="base-canvas-size">
              <p>Animation that can be paused and played by clicking on it</p>
            </RiveComponentPlayback>
            <p>{animationText}</p>
            <Button onClick={togglePlaying}>
              {isPlaying ? 'Pause' : 'Play'}
            </Button>
          </div>
        </>
      );
    }}
  </Story>
</Canvas>

#### useRive parameters

```tsx
useRive(params: UseRiveParameters, opts?: UseRiveOptions);
```

The parameters available to set on `useRive` can be found [here](https://github.com/rive-app/rive-wasm/blob/master/js/src/rive.ts#L843). These pass down to the web runtime `rive` instance created.

Additionally, there are other options to set on `useRive` that can be found [here](https://github.com/rive-app/rive-react/blob/main/src/types.ts#L6).
