If you’re building Flutter apps and looking for a predictable, testable, and scalable way to manage state — Riverpod is hands down one of the best choices. It smooths out many of the pain points you might have faced with older solutions while staying clean, modern, and flexible.
In this guide, we’ll explore what Riverpod is, why so many developers love it, how to set it up step-by-step, and the best practices I’ve learned using it in production. You’ll also get code examples you can copy straight into your own project.
My goal here is clarity — short explanations, concrete examples, and real-world advice. No fluff, just practical steps to help you ship features faster.
Overview
Riverpod is a provider-based state management library designed to be simple, testable, and robust. Unlike older approaches, it’s not tied to Flutter’s widget tree, which makes it easier to write clean architecture and simple unit tests.
The key ideas behind Riverpod are providers (which expose your state), ref (which lets providers communicate with one another), and lifecycle helpers like autoDispose and family. Once you understand these, everything else in Riverpod clicks into place.
Why Developers Choose Riverpod
- Independent of the widget tree: You can use providers anywhere in your app — even outside widgets.
- Easy to test: Override and inject dependencies cleanly during tests.
- Efficient updates: Riverpod rebuilds only what’s necessary, improving performance.
- Lifecycle control: Use
autoDisposeto automatically clean up unused state. - Composable and modular: Providers can depend on each other, making complex setups easier to reason about.
Step-by-Step Setup
1. Install Riverpod
Add this to your pubspec.yaml file:
flutter_riverpod: ^2.0.0 2. Wrap your app
Wrap the root of your app in ProviderScope so Riverpod can manage all providers:
void main() { runApp(ProviderScope(child: MyApp())); } 3. Create your first provider
Let’s start simple — a counter using StateProvider:
final counterProvider = StateProvider((ref) => 0);
class CounterWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final count = ref.watch(counterProvider);
return Text('Count: $count');
}
}
This uses ConsumerWidget and WidgetRef, which are the cleanest way to consume providers in widgets.
4. Update the state
ref.read(counterProvider.notifier).state++; 5. Handle async data with FutureProvider
Fetching async data is easy with FutureProvider — it gives you built-in loading, error, and data states:
final userProvider = FutureProvider((ref) async { final api = ref.read(apiServiceProvider); return api.fetchUser(); });
// Usage:
ref.watch(userProvider).when(
data: (user) => Text(user.name),
loading: () => CircularProgressIndicator(),
error: (e, st) => Text('Error: $e'),
);
Best Practices
- Keep providers small and focused: One job per provider keeps your logic clean and testable.
- Use
ref.watchin build methods andref.readin callbacks: This prevents unnecessary rebuilds. - Use
autoDisposefor short-lived state: For example, in search screens or temporary dialogs. - Organize providers by feature: Keep related providers in their own files or folders.
- Mock providers in tests: Use
ProviderScope(overrides: [...])to inject test doubles.
- Use
StateNotifierfor complex state that needs clear transitions. - Leverage
familyfor parameterized providers (e.g., per-user data). - Enable
ProviderObserverto log provider events when debugging. - Keep side effects (like API calls) in providers, not widgets — keep UI logic pure.
Examples
Example 1 — StateNotifier Counter
class CounterState { final int value; CounterState(this.value); }
class CounterNotifier extends StateNotifier {
CounterNotifier() : super(CounterState(0));
void increment() {
state = CounterState(state.value + 1);
}
}
final counterNotifierProvider =
StateNotifierProvider((ref) => CounterNotifier());
Example 2 — Parameterized Provider (family)
final userProvider = FutureProvider.family((ref, userId) async { final api = ref.read(apiServiceProvider); return api.fetchUserById(userId); });
// Usage:
final userId = '123';
final userAsync = ref.watch(userProvider(userId));
Conclusion
Riverpod hits the sweet spot between simplicity and power. It scales beautifully from small prototypes to complex apps. The key principles — small, testable providers and clear state management — will serve you well as your app grows.
Start small: wrap your app with ProviderScope, create a StateProvider, and build up from there. Once you’re comfortable, experiment with StateNotifier and FutureProvider for more advanced use cases.
If this helped you, save it for reference or share it with a teammate. And if you’d like a follow-up on testing Riverpod providers, let me know — I’ll write that next!
FAQ
Is Riverpod better than Provider?
Yes — Riverpod fixes many of Provider’s limitations. It’s independent of the widget tree, easier to test, and offers better lifecycle control. It’s the recommended choice for new projects.
When should I use StateNotifier instead of StateProvider?
Use StateProvider for simple mutable values. If your state involves logic or multiple transitions, go with StateNotifier.
How do I test Riverpod providers?
Wrap your tests with ProviderScope(overrides: []) to override providers. Use synchronous providers when possible for faster test runs.
Can I migrate from Provider to Riverpod?
Yes! You can migrate gradually — one feature at a time. Keep things modular and avoid full rewrites.