Rive Player

Rive runtime wrapped in the shared media surface. Controls-off by default (bare viewer); set controls for a play/pause overlay.

Installation

import { RivePlayer } from "@gradeui/ui"

The Rive runtime (@rive-app/react-canvas) is an optional dependency— it's installed by default with pnpm/npm, but consumers who don't use Rive can --no-optional to skip it. RivePlayer lazy-imports the runtime; if missing at runtime, it renders a friendly error.

Viewer mode (default)

Player mode

Props

Prop	Type	Default	Description
src	string	-	URL or path to the .riv file.
stateMachines	string \| string[]	-	State machine(s) to run.
artboard	string	-	Artboard name — omit to use the default.
controls	boolean	false	Show a minimal play/pause overlay.
autoPlay	boolean	true	Autoplay on mount. Respects reduced-motion.
loop	boolean	true	Loop animation on end.
pauseOffscreen	boolean	true	Pause when the surface leaves the viewport.
fit	"contain" \| "cover" \| "fill" \| "fitWidth" \| "fitHeight" \| "none"	"contain"	How the artboard sits inside the surface.
stateMachineInputs	Record<string, number \| boolean \| string>	-	Inputs passed to the state machine at mount.
aspect	"video" \| "square" \| "portrait" \| "wide" \| "auto"	"square"	Aspect ratio of the surface.
poster	string	-	Image shown while the runtime loads.

Sidecar

The Markdown sidecar Studio (and the Grade MCP server, when it ships) reads to understand this component — frontmatter, when- to-use guidance, and canonical examples. Authored once at packages/ui/components/ui/rive-player.md and shipped inside the published @gradeui/ui tarball.

---
name: RivePlayer
import: "@gradeui/ui"
props:
  - src: string — URL or path to the .riv file
  - stateMachines?: string | string[] — state machine(s) to run
  - artboard?: string — artboard name; omit to use default
  - controls?: boolean (default false) — viewer mode by default; set true for play/pause overlay
  - autoPlay?: boolean (default true) — respects reduced-motion
  - loop?: boolean (default true)
  - pauseOffscreen?: boolean (default true)
  - fit?: "contain" | "cover" | "fill" | "fitWidth" | "fitHeight" | "none" (default "contain")
  - stateMachineInputs?: Record<string, number | boolean | string>
  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "square")
  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg")
  - poster?: string — image shown while the runtime loads
when_to_use: Rive runtime wrapped in the shared media surface. Reach for Rive when you need interactive state-machine animations driven by scroll/hover/input. For non-interactive looping video, use VideoPlayer; for shader-driven backgrounds, use ThreeScene.
composes_with: [MediaSurface (internal), Card, any container]
aliases: [rive, riv, animation, animated, lottie]
notes: The Rive runtime (`@rive-app/react-canvas`) is an optional dependency of `@gradeui/ui` — lazy-imported at mount. Consumers who don't use Rive can install with `--no-optional` and the dep is skipped; RivePlayer renders a friendly error if the runtime is missing. When no `src` is given RivePlayer renders an empty surface — ALWAYS pass `src`. If you don't have a specific file, use the public Rive CDN sample "https://cdn.rive.app/animations/vehicles.riv" with `stateMachines="bumpy"` — a known-working demo.
---

```jsx
// Known-working public sample — use this when you don't have a specific .riv
<RivePlayer
  src="https://cdn.rive.app/animations/vehicles.riv"
  stateMachines="bumpy"
  aspect="square"
/>

// Player mode with state-machine inputs
<RivePlayer
  src="/button.riv"
  stateMachines="Hover"
  stateMachineInputs={{ isHovered: true }}
  controls
/>
```