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.