rive-interactive

What this skill does

# Rive Interactive - State Machine-Based Vector Animation

## Overview

Rive is a state machine-based animation platform that enables designers to create interactive vector animations with complex logic and runtime interactivity. Unlike timeline-only animation tools (like Lottie), Rive supports state machines, input handling, and two-way data binding between application code and animations.

**Key Features**:
- State machine system for complex interactive logic
- ViewModel API for two-way data binding
- Input handling (boolean, number, trigger inputs)
- Custom events for animation-to-code communication
- Runtime property control (colors, strings, numbers, enums)
- Cross-platform support (Web, React, React Native, iOS, Android, Flutter)
- Small file sizes with vector graphics

**When to Use This Skill**:
- Creating UI animations with complex state transitions
- Building interactive animated components (buttons, toggles, loaders)
- Implementing game-like UI with state-driven animations
- Binding real-time data to animated visualizations
- Creating animations that respond to user input
- Working with designer-created animations requiring runtime control

**Alternatives**:
- **Lottie** (lottie-animations): For simpler timeline-based animations without state machines
- **Framer Motion** (motion-framer): For code-first React animations with spring physics
- **GSAP** (gsap-scrolltrigger): For timeline-based web animations with precise control

## Core Concepts

### 1. State Machines

State machines define animation behavior with states and transitions:
- **States**: Different animation states (e.g., idle, hover, pressed)
- **Inputs**: Variables that control transitions (boolean, number, trigger)
- **Transitions**: Rules for moving between states
- **Listeners**: React hooks to respond to state changes

### 2. Inputs

Three input types control state machine behavior:
- **Boolean**: On/off states (e.g., isHovered, isActive)
- **Number**: Numeric values (e.g., progress, volume)
- **Trigger**: One-time events (e.g., click, submit)

### 3. ViewModels

Data binding system for dynamic properties:
- **String Properties**: Text content (e.g., username, title)
- **Number Properties**: Numeric data (e.g., stock price, score)
- **Color Properties**: Dynamic colors (hex values)
- **Enum Properties**: Selection from predefined options
- **Trigger Properties**: Animation events

### 4. Events

Custom events emitted from animations:
- **General Events**: Custom named events
- **Event Properties**: Data attached to events
- **Event Listeners**: React hooks to handle events

## Common Patterns

### Pattern 1: Basic Rive Animation

**Use Case**: Display a simple Rive animation in React

**Implementation**:

```bash
# Installation
npm install rive-react
```

```jsx
import Rive from 'rive-react';

export default function SimpleAnimation() {
  return (
    <Rive
      src="animation.riv"
      artboard="Main"
      animations="idle"
      layout={{ fit: "contain", alignment: "center" }}
      style={{ width: '400px', height: '400px' }}
    />
  );
}
```

**Key Points**:
- `src`: Path to .riv file
- `artboard`: Which artboard to display
- `animations`: Which animation timeline to play
- `layout`: How animation fits in container

### Pattern 2: State Machine Control with Inputs

**Use Case**: Control animation states based on user interaction

**Implementation**:

```jsx
import { useRive, useStateMachineInput } from 'rive-react';

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

  // Get state machine inputs
  const hoverInput = useStateMachineInput(
    rive,
    'Button State Machine',
    'isHovered',
    false
  );

  const clickInput = useStateMachineInput(
    rive,
    'Button State Machine',
    'isClicked',
    false
  );

  return (
    <div
      onMouseEnter={() => hoverInput && (hoverInput.value = true)}
      onMouseLeave={() => hoverInput && (hoverInput.value = false)}
      onClick={() => clickInput && clickInput.fire()} // Trigger input
      style={{ cursor: 'pointer' }}
    >
      <RiveComponent style={{ width: '200px', height: '100px' }} />
    </div>
  );
}
```

**Input Types**:
- Boolean: `input.value = true/false`
- Number: `input.value = 50`
- Trigger: `input.fire()`

### Pattern 3: ViewModel Data Binding

**Use Case**: Bind application data to animation properties

**Implementation**:

```jsx
import { useRive, useViewModel, useViewModelInstance,
         useViewModelInstanceString, useViewModelInstanceNumber } from 'rive-react';
import { useEffect, useState } from 'react';

export default function Dashboard() {
  const [stockPrice, setStockPrice] = useState(150.0);

  const { rive, RiveComponent } = useRive({
    src: 'dashboard.riv',
    autoplay: true,
    autoBind: false, // Manual binding for ViewModels
  });

  // Get ViewModel and instance
  const viewModel = useViewModel(rive, { name: 'Dashboard' });
  const viewModelInstance = useViewModelInstance(viewModel, { rive });

  // Bind properties
  const { setValue: setTitle } = useViewModelInstanceString(
    'title',
    viewModelInstance
  );

  const { setValue: setPrice } = useViewModelInstanceNumber(
    'stockPrice',
    viewModelInstance
  );

  useEffect(() => {
    if (setTitle) setTitle('Stock Dashboard');
  }, [setTitle]);

  useEffect(() => {
    if (setPrice) setPrice(stockPrice);
  }, [setPrice, stockPrice]);

  // Simulate real-time updates
  useEffect(() => {
    const interval = setInterval(() => {
      setStockPrice((prev) => prev + (Math.random() - 0.5) * 10);
    }, 1000);

    return () => clearInterval(interval);
  }, []);

  return <RiveComponent style={{ width: '800px', height: '600px' }} />;
}
```

**ViewModel Property Hooks**:
- `useViewModelInstanceString` - Text properties
- `useViewModelInstanceNumber` - Numeric properties
- `useViewModelInstanceColor` - Color properties (hex)
- `useViewModelInstanceEnum` - Enum selection
- `useViewModelInstanceTrigger` - Animation triggers

### Pattern 4: Handling Rive Events

**Use Case**: React to events emitted from Rive animation

**Implementation**:

```jsx
import { useRive, EventType, RiveEventType } from 'rive-react';
import { useEffect } from 'react';

export default function InteractiveRating() {
  const { rive, RiveComponent } = useRive({
    src: 'rating.riv',
    stateMachines: 'State Machine 1',
    autoplay: true,
    automaticallyHandleEvents: true,
  });

  useEffect(() => {
    if (!rive) return;

    const onRiveEvent = (event) => {
      const eventData = event.data;

      if (eventData.type === RiveEventType.General) {
        console.log('Event:', eventData.name);

        // Access event properties
        const rating = eventData.properties.rating;
        const message = eventData.properties.message;

        if (rating >= 4) {
          alert(`Thanks for ${rating} stars: ${message}`);
        }
      }
    };

    rive.on(EventType.RiveEvent, onRiveEvent);

    return () => {
      rive.off(EventType.RiveEvent, onRiveEvent);
    };
  }, [rive]);

  return <RiveComponent style={{ width: '400px', height: '300px' }} />;
}
```

### Pattern 5: Preloading Rive Files

**Use Case**: Optimize load times by preloading animations

**Implementation**:

```jsx
import { useRiveFile, useRive } from 'rive-react';

export default function PreloadedAnimation() {
  const { riveFile, status } = useRiveFile({
    src: 'large-animation.riv',
  });

  const { RiveComponent } = useRive({
    riveFile: riveFile,
    artboard: 'Main',
    autoplay: true,
  });

  if (status === 'loading') {
    return <div>Loading animation...</div>;
  }

  if (status === 'failed') {
    return <div>Failed to load animation</div>;
  }

  return <RiveComponent style={{ width: '600px', height: '400px' }} />;
}
```

### Pattern 6: Controlled Animation with Refs

**Use Case**: Control animation from parent component

**Imple