What is Riverpod?
Riverpod is a state management library that works without BuildContext, catches many mistakes at compile time, and makes testing easy. Many teams use it for larger apps.
API note: Riverpod changes between major versions. The ideas in this lesson (providers, ref.watch, Notifier) stay the same. For exact details, check the current Riverpod documentation.
Install
bash
flutter pub add flutter_riverpod
Step 1: Wrap the App in ProviderScope
dart
import 'package:flutter_riverpod/flutter_riverpod.dart';
void main() {
runApp(const ProviderScope(child: MyApp()));
}
Step 2: A Simple Provider (Read-Only Value)
dart
final greetingProvider = Provider<String>((ref) => 'Hello Riverpod');
Providers are declared as global final variables. That is fine, because the state itself is stored by Riverpod, not in the variable.
Step 3: A Notifier for Changing State
dart
class CounterNotifier extends Notifier<int> {
@override
int build() => 0; // the initial state
void increment() => state++;
void decrement() => state--;
void reset() => state = 0;
}
final counterProvider = NotifierProvider<CounterNotifier, int>(CounterNotifier.new);
Step 4: Use It in the UI
dart
class CounterPage extends ConsumerWidget {
const CounterPage({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final count = ref.watch(counterProvider); // rebuilds on change
return Scaffold(
body: Center(child: Text('$count', style: const TextStyle(fontSize: 48))),
floatingActionButton: FloatingActionButton(
onPressed: () => ref.read(counterProvider.notifier).increment(),
child: const Icon(Icons.add),
),
);
}
}
| Call | Meaning |
ref.watch(provider) | Get the value and rebuild when it changes (use in build) |
ref.read(provider) | Get the value once without listening (use in callbacks) |
ref.read(provider.notifier) | Get the Notifier to call its methods |
ref.listen(provider, ...) | React to changes, for example show a SnackBar |
A List of Todos
dart
class TodosNotifier extends Notifier<List<String>> {
@override
List<String> build() => [];
void add(String todo) {
state = [...state, todo]; // create a NEW list so the change is noticed
}
void remove(String todo) {
state = state.where((t) => t != todo).toList();
}
}
final todosProvider = NotifierProvider<TodosNotifier, List<String>>(TodosNotifier.new);
Immutable state: Always assign a new object to state. Changing the old list in place, such as state.add(x), is not noticed by Riverpod and the UI will not update.
Async Data: FutureProvider and AsyncValue
dart
final userProvider = FutureProvider<String>((ref) async {
await Future.delayed(const Duration(seconds: 2));
return 'Asha';
});
class UserView extends ConsumerWidget {
const UserView({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final user = ref.watch(userProvider);
return user.when(
loading: () => const CircularProgressIndicator(),
error: (e, st) => Text('Error: $e'),
data: (name) => Text('Hello $name'),
);
}
}
AsyncValue forces you to handle the loading, error and data states, so you never forget them.
Providers Can Depend on Each Other
dart
final totalProvider = Provider<int>((ref) {
final todos = ref.watch(todosProvider);
return todos.length; // recalculated when todos change
});
Tip: Use ConsumerStatefulWidget when you need both Riverpod and a State class with controllers or initState.
Conclusion
Riverpod keeps state outside the widget tree, which makes it easy to test and share. Learn watch versus read and always create new state objects.
Quick Summary: Wrap with ProviderScope, define providers, use ConsumerWidget with ref.watch and call notifier methods with ref.read.