Skip to content
Blog

Driving Interactive Rive Animations in Flutter: State Machines, Data Binding and Renderers

A working guide to rive in Flutter: RiveNative.init, FileLoader and RiveWidgetBuilder, state machine inputs versus view model data binding, renderer choice, and disposal.

Published on • November 12, 2026

AI Assistant

Our Lottie vs Rive comparison post covered the decision: when an animation has to react to input or app state, Rive’s state machines win over a linear timeline. This post is about the other half of the job, actually driving a .riv file from Flutter code: initializing the runtime, loading files, wiring a state machine, moving from legacy inputs to data binding, and choosing a renderer without tripping over disposal or WebGL limits.

Install, register assets, initialize

dependencies:
  rive: ^0.14.11

flutter:
  assets:
    - assets/vehicles.riv

rive 0.14.11 (published August 2026) depends on rive_native 0.1.11, a Dart plugin that wraps the Rive C++ runtime and the Rive Renderer. Prebuilt native libraries download automatically during flutter run and flutter build; if that ever fails, the manual fallback is dart run rive_native:setup --verbose --clean --platform macos. Note that rive_common 0.4.15 (unlisted on pub.dev since December 2024) belongs to the old stack, along with the legacy runtime that stopped at rive 0.13.20, so ignore it if dependency analysis surfaces it.

Call the native init once at startup so the first graphic does not pay for it:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await RiveNative.init();
  runApp(const MyApp());
}

The runtime also initializes lazily on first file load, but an explicit call in main() keeps first-frame behavior predictable. A 0.15.0-dev.4 prerelease exists with its own migration guide, so pin the stable ^0.14.11 unless you are testing the new major.

Load files through FileLoader

FileLoader is the recommended entry point because it owns loading, caching and disposal:

final fileLoader = FileLoader.fromAsset(
  'assets/vehicles.riv',
  riveFactory: Factory.rive,
);

FileLoader.fromUrl(...) loads from a CDN and FileLoader.fromFile(...) wraps an already loaded File, which is how you reuse one download across screens. Lower-level alternatives exist (File.asset, File.url, File.path, File.decode) but then you manage the File lifetime yourself. Loading failures surface as typed exceptions: RiveFileLoaderException, RiveArtboardException, RiveStateMachineException, and RiveDataBindException, so you can distinguish a missing asset from a typo in an artboard name.

Render with RiveWidgetBuilder

RiveWidget renders a graphic, and RiveWidgetBuilder handles the loading states around it:

RiveWidgetBuilder(
  fileLoader: fileLoader,
  builder: (context, state) => switch (state) {
    RiveLoading() => const Center(child: CircularProgressIndicator()),
    RiveFailed() => Text('Could not load: ${state.error}'),
    RiveLoaded() => RiveWidget(
        controller: state.controller,
        fit: Fit.cover,
        alignment: Alignment.center,
      ),
  },
);

RiveWidget exposes fit, alignment, hitTestBehavior (default opaque, which is what makes taps reach the artboard), cursor, drawOrder, and renderResolution. When you need explicit control, build the controller yourself with RiveWidgetController(file, artboardSelector: ArtboardSelector.byName('MyArtboard'), stateMachineSelector: StateMachineSelector.byName('Drive')), then hand it to RiveWidget.

Inputs are legacy, data binding is the contract

For years the contract between code and a Rive file was a pair of primitives: state machine inputs (numbers, booleans, triggers) pushed in, and events fired back. The migration guide replaces both with view model properties:

CapabilityInputsEventsView model properties
Numbers, booleansyesyesyes
Triggersyesnoyes
Stringsnoyesyes
Enums, colors, lists, images, nested models, artboardsnonoyes

Existing files keep working, and the editor ships a “Convert Inputs to View Models” action, but new work should bind data:

final controller = RiveWidgetController(file);
final vm = controller.dataBind(DataBind.byName('CarState'));

// Push state into the file
vm.number('speed').value = 88;
vm.boolean('nightMode').value = true;

// React to changes the file makes (animation, listener or script)
// by subscribing to the property's change notifications.

Two practical wins: text runs bound to a string property replace the brittle “find the text run by name and path” lookups of the old API, and a single property can drive several elements at once, which is what the guide means when it says view model properties can be shared across a file. Constraints remain the right tool for purely visual object-to-object links.

Renderer choice and the Impeller caveat

Every File picks its renderer once, at creation: Factory.rive draws with the Rive Renderer (required for features like Vector Feathering), Factory.flutter paints through Skia or Impeller. Graphics from one file share that choice. Three consequences worth planning for:

  • Complex art, text-heavy scenes and 3D content favor Factory.rive; simple decorative motion is fine on either.
  • RivePanel can draw many RiveWidgets into one shared texture, but only with Factory.rive, and it prevents interleaving Rive draws with Flutter’s own.
  • On the web, each Factory.rive widget that owns its texture takes a WebGL context, and browsers cap live contexts at around 16 (shared with Flutter’s CanvasKit surfaces). Lists of Rive items on web should share one texture via RivePanel, or use Factory.flutter.

If a graphic looks wrong only on iOS, the documented triage is to rule out Impeller first: flutter run --no-enable-impeller. If Skia shows the same bug, it is a Rive issue; if only Impeller does, reproduce on the master channel before filing against Flutter.

Disposal and the build that mysteriously fails

With RiveWidgetBuilder you dispose only the loader, and the builder manages the rest:

@override
void dispose() {
  fileLoader.dispose(); // also releases the underlying File
  super.dispose();
}

Manual setup requires reverse order: viewModelInstance.dispose(), then controller.dispose(), then file.dispose(). Disposal also releases the widget’s WebGL context on web, so route transitions that churn Rive widgets stay cheap thanks to a small reuse pool. When native libraries look stale, the fix is almost always flutter clean && flutter pub get && flutter run, and unit tests need the libraries downloaded first with dart run rive_native:setup --verbose --clean --platform windows (or macos/linux) before flutter test.

Takeaway: Pin rive 0.14.11, call RiveNative.init() in main(), load through a shareable FileLoader inside RiveWidgetBuilder, drive files with view model properties instead of legacy inputs and events, pick Factory.rive deliberately (and share one texture per list on web), and always dispose loaders, controllers and files in reverse creation order.

Sources