Skip to main content
TypeScript schemas require the new React Native runtime, @rive-app/react-native 0.5.0 or later. See the migration guide to upgrade.
You can generate a TypeScript schema for each .riv file. With it, artboard, state machine, view model, property, and enum names are checked at compile time, and your editor autocompletes them. A typo becomes a compile error instead of a runtime failure. A schema is a .riv.d.ts file next to the .riv file. It lists the file’s artboards, state machines, view models, and enums. It contains only types, so nothing changes in your bundle. Types only apply when you load the Rive file with import. TypeScript finds the .riv.d.ts file automatically, with no tsconfig change. require(...) returns any, so it stays untyped even if a schema exists. This lets you adopt schemas one file at a time.

Quick start

1

Install @rive-app/canvas

The generator uses it to read .riv files. It’s a dev dependency only and is not bundled into your app.
2

Generate schemas

Commit the generated files. The output is stable, so regenerating an unchanged file gives no diff.
3

Import the Rive file

Importing a .riv file needs riv in Metro’s assetExts. See loading Rive files.

What gets typed

A generated schema looks like this:
rewards.riv.d.ts
The types flow from the import, so you don’t need to annotate anything. Artboard and state machine names on RiveView are checked, and the state machine must belong to the chosen artboard:
View model names, property paths, and enum values are checked too. Each hook only accepts paths to properties of its type, including nested property paths:
Enum values are checked against the value names defined in the Rive file. To reuse an enum’s values in your own types, use EnumValues:

Referenced assets

Out-of-band assets are listed in referencedAssets, keyed by the asset name and unique identifier as exported from the Rive editor. The referencedAssets option of useRiveFile is checked against that list: an unknown key or a wrong type is a compile error.
See loading assets for the ways to load out-of-band assets.

Typing your own components

To pass a typed Rive file or view model instance to another component, use TypedRiveFile and TypedViewModelOf:

Files loaded from a URL

A .riv.d.ts file only types a local import. For a URL, generate a schema type with --out and pass it as a generic:
The type is named after the file (rewards.riv → RewardsSchema). Use --name to pick another name.

Keeping schemas up to date

Regenerate after you edit a .riv file, then fix what TypeScript flags. Renamed artboards, removed properties, and changed enum values show up as errors where they’re used. To catch stale schemas in CI, regenerate and fail if anything changed:

Limits

  • Nested property paths are typed up to two levels deep ('a/b/leaf'). Deeper paths work at runtime but need a cast.
  • Paths must be string literals. To build a path at runtime, use a view model instance without a schema.
  • List items are untyped, because the schema can’t know which view model each item uses.
  • A nested view model is only typed if it has a default instance in the file. Otherwise its paths aren’t typed.

Troubleshooting

Load the Rive file with import, not require(...). Check that a .riv.d.ts file with the same name sits next to the .riv file.
The schema was generated for a different version of @rive-app/react-native. Run npx rive-gen-types again.