🚀 Migrating to Rive Flutter 0.14.0

Rive Flutter 0.14.0 is one of the biggest updates ever released for the Flutter runtime.

This version completely replaces the previous Dart-based runtime with the native Rive C++ Runtime, enabling better performance, faster feature support, and long-term stability.

However, this update also introduces breaking API changes and new workflows for loading files, controlling animations, and interacting with state machines.

This article walks you through everything you need to know to migrate to the latest stable version smoothly.

🎉 What’s New in Rive Flutter 0.14.0

The 0.14.0 update now uses the native Rive Renderer, unlocking full compatibility with the latest Rive editor features.

New Features Supported

🔥 Rive Renderer (full fidelity graphics)

🔄 Data Binding

📐 Layouts

🌀 Scrolling

➗ N-Slicing

✏️ Vector Feathering

➕ All features introduced in Rive Editor since the previous Flutter runtime

🚀 Includes all fixes from the Rive C++ runtime

📦 New prebuilt native libraries (via rive_native)

🗑️ Removal of Dart-driven runtime (rive_common deprecated)

🛠 Requirements
Updated SDK versions
sdk: ">=3.5.0 <4.0.0"
flutter: ">=3.3.0"

Mandatory Initialization

You must initialize Rive before using it:

import 'package:rive/rive.dart';

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

If you don't call RiveNative.init(), you will face runtime exceptions.

🔄 Quick Migration Checklist

✔️ Update your dependencies to rive: ^0.14.0
✔️ Add await RiveNative.init() in main()
✔️ Replace old widget APIs (Rive, RiveAnimation) → RiveWidget / RiveWidgetBuilder
✔️ Migrate controllers → RiveWidgetController, SingleAnimationPainter, etc.
✔️ Update file loading code
✔️ Update state machine triggers and inputs
✔️ Test your interactions and animations

💔 Removed APIs (What You Must Replace)
Removed Replacement
Rive, RiveAnimation RiveWidget, RiveWidgetBuilder
RiveAnimationController RiveWidgetController
OneShotAnimation, SimpleAnimation SingleAnimationPainter
StateMachineController StateMachine
SMITrigger, SMIBool, SMINumber TriggerInput, BooleanInput, NumberInput
RiveFile File
FileAssetLoader family new assetLoader: callback

These are major changes—many old code paths no longer exist.

📦 Loading Rive Files (New API)

The old RiveFile is gone.
Use the new File class:

Decode from bytes
final file = await File.decode(bytes, factory: Factory.rive);

Getting artboards
final artboard = file.defaultArtboard();
final custom = file.artboard('MyArtboard');

Factory options

Factory.rive → Rive Renderer

Factory.flutter → Flutter's Skia/Impeller renderer

Vector feathering works only with Factory.rive.

API changes summary
Old New
RiveFile.import(bytes) File.decode(bytes, factory)
mainArtboard defaultArtboard()
artboardByName('A') artboard('A')
RiveFile.network() File.url()
RiveFile.file() File.path()
🎨 Widget Migration

Use the new RiveWidget and RiveWidgetBuilder.

Example: Using RiveWidgetBuilder
class SimpleAssetAnimation extends StatefulWidget {
const SimpleAssetAnimation({super.key});

@override
State createState() => _SimpleAssetAnimationState();
}

class _SimpleAssetAnimationState extends State {
late final fileLoader = FileLoader.fromAsset(
'assets/off_road_car.riv',
riveFactory: Factory.rive,
);

@override
void dispose() {
fileLoader.dispose();
super.dispose();
}

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Simple Animation')),
body: Center(
child: RiveWidgetBuilder(
fileLoader: fileLoader,
builder: (context, state) => switch (state) {
RiveLoading() => const CircularProgressIndicator(),
RiveFailed() => Text('Failed to load: ${state.error}'),
RiveLoaded() => RiveWidget(
controller: state.controller,
fit: Fit.cover,
),
},
),
),
);
}
}

🎛 Controller Migration
Old vs New API
Old New
RiveAnimationController RiveWidgetController
StateMachineController StateMachine
SimpleAnimation, OneShotAnimation SingleAnimationPainter
Using RiveWidgetController
final file = await File.asset(
'assets/off_road_car.riv',
riveFactory: Factory.rive,
);

final controller = RiveWidgetController(file);
final artboard = controller.artboard;

// Auto-bind data bindings
final viewModel = controller.dataBind(DataBind.auto());

Selecting artboards or state machines manually
final controller = RiveWidgetController(
file,
artboardSelector: ArtboardSelector.byName('Main'),
stateMachineSelector: StateMachineSelector.byName('State Machine 1'),
);

🎮 Handling State Machine Inputs

Old API classes (SMIBool, SMINumber, etc.) are removed.

New API
stateMachine.trigger('jump');
stateMachine.boolean('isWalking');
stateMachine.number('speed');

Nested inputs
stateMachine.boolean('isVisible', path: 'player/ui');

Important

Dispose inputs when no longer needed:

input.dispose();

📡 Handling Rive Events (New API)

RiveEvent → removed
Event → new sealed type:

OpenUrlEvent

GeneralEvent

Listen to events
controller.stateMachine.addEventListener(_onEvent);

void _onEvent(Event event) {
print(event.property('score'));
}

Convenient property access:

event.numberProperty('value');
event.booleanProperty('flag');
event.stringProperty('message');

🧩 Layout Changes

BoxFit → replaced with Fit

Fit.contain
Fit.cover
Fit.layout // NEW option

🖼 Asset Loading Changes

The entire FileAssetLoader system is removed in favor of a simpler callback.

New API
assetLoader: (asset, bytes) {
asset.decode(bytes); // For images, fonts, audio
}

Conversions:

Old New
ImageAsset.parseBytes factory.decodeImage
FontAsset.parseBytes factory.decodeFont
AudioAsset.parseBytes factory.decodeAudio
ImageAsset.image = ... asset.renderImage()
✍️ Updating Text at Runtime

TextValueRun cannot be accessed directly anymore.

New API
artboard.setText('Hello Rive');
artboard.getText('name');

Supports optional paths:

artboard.setText('Score: 10', path: 'ui/score');

🚫 Missing Features (For Now)

The following features are not yet implemented in 0.14.0:

Automatic CDN asset loading

speedMultiplier

useArtboardSize

clipRect

isTouchScrollEnabled

dynamicLibraryHelper

Expect updates in future releases.

🧹 Removed Dart Runtime Code

The Dart-based runtime is gone from:

src/controllers

src/core

src/generated

rive_core

utilities

All Rive logic now flows through FFI → C++ Core Runtime.

✅ Final Thoughts

Rive Flutter 0.14.0+ is a massive step forward:

Faster performance

More features

Native parity with the Rive Editor

Cleaner APIs

Long-term maintainability

Although migration requires code updates, the new architecture is more powerful and future-ready.

If you are upgrading a production app, follow the checklist carefully and test your Rive interactions after updating.