Nuxt-Rive

Integrate Rive into your Nuxt application.

This library allows full control over Rive files with a high-level API for hooking up many simple interactions and animations, as well as a low-level API that allows you to drive your own render loop to create multiple artboards, animations, and state machines all in one canvas.

✨ Release Notes ▶️ Online playground 📖 Documentation

Quick Setup

1. Add nuxt-rive dependency to your project

# Using pnpm
pnpm add -D nuxt-rive

# Using yarn
yarn add --dev nuxt-rive

# Using npm
npm install --save-dev nuxt-rive

2. Add nuxt-rive to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-rive'
  ]
})

Basic Usage

Use the <NuxtRive> component to render your animations:

<template>
  <ClientOnly>
    <NuxtRive
      :rive-params="{
        src: 'https://cdn.rive.app/animations/vehicles.riv',
        autoplay: true,
        stateMachines: 'bumpy',
        artboard: 'Truck'
      }"
      :options="{
        fitCanvasToArtboardHeight: true,
        useOffscreenRenderer: true
      }"
    />
  </ClientOnly>
</template>

Features

• Component-Based: Easy-to-use <NuxtRive> component.
• SSR Compatible: Works seamlessly with Nuxt (use <ClientOnly> wrapper).
• Interactive: Full control via useRiveStateMachineInput.
• Dynamic Text: Update text runs at runtime with the text-runs prop.
• Events: Listen to Rive events like Play, Pause, Stop, Loop, and StateChange.
• Efficient: Uses @rive-app/webgl for high-performance rendering.
• Nuxt DevTools: Integrated DevTools tab to view and manage your Rive assets.

Nuxt DevTools Integration

nuxt-rive comes with a custom tab for Nuxt DevTools that allows you to:

• Explore all Rive assets in your project (public and assets directories).
• Preview animations directly within the DevTools.
• Inspect file details like size and path.
• Copy usage snippets for quick integration into your components.

To use it, simply open Nuxt DevTools in your development environment and click on the Nuxt Rive tab.

Component Props

| Prop | Type | Description | | --- | --- | --- | | rive-params | UseRiveParameters | Configuration object for the Rive instance (src, artboard, stateMachines, etc.). | | options | UseRiveOptions | Runtime options like fitCanvasToArtboardHeight and useOffscreenRenderer. | | text-runs | Record<string, string> | (New) Replaces text run values dynamically. Key is the run name, value is the new text. |

rive-params Interface

interface UseRiveParameters {
  src?: string;
  artboard?: string;
  animations?: string | string[];
  stateMachines?: string | string[];
  layout?: Layout;
  autoplay?: boolean;
  // ...and more standard Rive parameters
}

Events

The <NuxtRive> component emits the following events:

• @rive-is-loaded: Triggered when the Rive instance is fully loaded. Returns the Rive instance.
• @play: Triggered when an animation starts playing.
• @pause: Triggered when an animation is paused.
• @stop: Triggered when an animation stops.
• @loop: Triggered when an animation loops.
• @statechange: Triggered when a state machine changes state.

Composables

useRiveStateMachineInput

Helper composable to control State Machine inputs (Triggers, Booleans, Numbers).

const { RiveInstance } = await useRive() // or get instance from @rive-is-loaded

// Trigger an input
useRiveStateMachineInput(RiveInstance, 'StateMachineName', 'InputName').fire()

// Set a boolean
const boolInput = useRiveStateMachineInput(RiveInstance, 'StateMachineName', 'BooleanInput')
boolInput.value = true

// Set a number
const numInput = useRiveStateMachineInput(RiveInstance, 'StateMachineName', 'NumberInput')
numInput.value = 50

Dynamic Text Example

<template>
  <NuxtRive
    :rive-params="{ src: 'my-file.riv' }"
    :text-runs="{
      'MyTextRun': 'Dynamic Value',
      'Score': '100'
    }"
  />
</template>

Contributing

1. Install dependencies with pnpm.
2. Run pnpm dev:prepare to generate stubbed dist directory.
3. Make your changes.
4. Run pnpm lint to verify that there is no issues (consider adding tests).
5. Submit a PR.

License

This repository is licensed under the MIT License. Feel free to use the code and modify it according to your needs.