# Rive Embedding Patterns ## Plain HTML (No Framework) Use the canvas runtime via unpkg CDN. Rive requires a `` element and JS instantiation (no web component like Lottie). ```html ``` **Important:** Always call `resizeDrawingSurfaceToCanvas()` in `onLoad` for crisp rendering on Retina/high-DPI displays. No npm install required when using the CDN. The `rive` global is available after the script loads. ### Self-hosting .riv files Rive has no public CDN like lottie.host. Always self-host `.riv` files: ```bash # Download from Rive Marketplace or export from editor # Place in your public directory mkdir -p public/animations cp my-animation.riv public/animations/ ``` Then reference as `/animations/my-animation.riv` in the `src` property. ### Rive constructor options ```javascript new rive.Rive({ src: '/animations/my-animation.riv', canvas: document.getElementById('canvas'), autoplay: true, stateMachines: 'State Machine 1', onLoad: () => { /* resize, access inputs */ }, onStateChange: (event) => { /* state changed */ }, }); ``` | Option | Type | Default | Description | |--------|------|---------|-------------| | `src` | string | required | URL or path to `.riv` file | | `canvas` | HTMLCanvasElement | required | Target canvas element | | `autoplay` | boolean | false | Start playing immediately | | `stateMachines` | string \| string[] | - | State machine name(s) to load | | `animations` | string \| string[] | - | Animation name(s) to play (if not using state machines) | | `artboard` | string | first | Artboard name (if `.riv` has multiple) | | `onLoad` | function | - | Callback when animation loads | | `onStateChange` | function | - | Callback on state machine transitions | ## React ```bash npm install @rive-app/react-webgl2 ``` ### Simple component ```tsx import Rive from '@rive-app/react-webgl2'; function MyAnimation() { return ( ); } ``` ### With state machine control ```tsx import { useRive, useStateMachineInput } from '@rive-app/react-webgl2'; function InteractiveButton() { const { rive, RiveComponent } = useRive({ src: '/animations/button.riv', stateMachines: 'Button State', autoplay: true, }); const hoverInput = useStateMachineInput(rive, 'Button State', 'isHovered'); const clickTrigger = useStateMachineInput(rive, 'Button State', 'onClick'); return ( hoverInput && (hoverInput.value = true)} onMouseLeave={() => hoverInput && (hoverInput.value = false)} onClick={() => clickTrigger?.fire()} /> ); } ``` ### Rive component props | Prop | Type | Default | Description | |------|------|---------|-------------| | `src` | string | required | URL or path to `.riv` file | | `stateMachines` | string \| string[] | - | State machine name(s) | | `animations` | string \| string[] | - | Animation name(s) | | `artboard` | string | first | Artboard name | | `autoplay` | boolean | true | Start playing immediately | | `style` | CSSProperties | - | Container styles | ### useRive hook ```tsx const { rive, RiveComponent } = useRive({ src: '/animations/my-animation.riv', stateMachines: 'State Machine 1', autoplay: true, }); ``` Returns: - `rive` — the Rive instance (null until loaded). Use for `.play()`, `.pause()`, `.stop()`. - `RiveComponent` — React component rendering the canvas. Must be in the DOM for Rive to instantiate. ### useStateMachineInput hook ```tsx const input = useStateMachineInput(rive, 'stateMachineName', 'inputName'); ``` Returns the input object or `null` (until rive loads). Input types: - **Trigger**: call `input.fire()` - **Boolean**: set `input.value = true/false` - **Number**: set `input.value = 0.5` ## Vue No dedicated Vue package. Use the canvas runtime directly. ```bash npm install @rive-app/canvas ``` ```vue ``` ### With state machine control (Vue) ```vue ``` ## Svelte / SvelteKit No dedicated Svelte package. Use the canvas runtime with Svelte actions. ```bash npm install @rive-app/canvas ``` ```svelte ``` ### With state machine control (Svelte) ```svelte ``` ## State Machine Input Types All frameworks use the same underlying API to control state machines: | Input Type | How to Set | Example | |------------|-----------|---------| | **Trigger** | `.fire()` | Button click, submit action | | **Boolean** | `.value = true/false` | Hover state, toggle, enabled/disabled | | **Number** | `.value = 0.5` | Progress bar, slider, scroll position | Access inputs after the Rive instance loads: ```javascript const inputs = riveInstance.stateMachineInputs('State Machine Name'); const myTrigger = inputs.find(i => i.name === 'triggerName'); const myBool = inputs.find(i => i.name === 'isHovered'); const myNumber = inputs.find(i => i.name === 'progress'); myTrigger.fire(); myBool.value = true; myNumber.value = 0.75; ``` ## Series Barrel File Pattern Same pattern as Lottie series, but with `.riv` paths (self-hosted): ```typescript // src/animations/index.ts export const animations = { toggle: '/animations/toggle.riv', button: '/animations/button.riv', checkbox: '/animations/checkbox.riv', loading: '/animations/loading.riv', success: '/animations/success.riv', } as const; export type AnimationKey = keyof typeof animations; ``` ### React series wrapper ```tsx import { useRive } from '@rive-app/react-webgl2'; import { animations, type AnimationKey } from '@/animations'; interface RiveAnimationProps { name: AnimationKey; size?: number; stateMachine?: string; } export function RiveAnimation({ name, size = 200, stateMachine = 'State Machine 1' }: RiveAnimationProps) { const { RiveComponent } = useRive({ src: animations[name], stateMachines: stateMachine, autoplay: true, }); return ; } ``` Usage: `` ## Speed Guidelines by Brand Energy Rive doesn't have a simple `speed` prop like Lottie. To control pacing: 1. **Design-time**: Set animation duration in the Rive editor 2. **Runtime number inputs**: If the Rive file exposes a speed/rate number input, set it via state machine 3. **Playback rate**: Use `rive.play()` with custom time advance in the low-level API (advanced) For most cases, animation pacing should be baked into the `.riv` file at design time.