references/riverpod-state.md
GitHubRiverpod State Management
Riverpod 2.0 state management guide covering provider types, notifier patterns, and widget integration.
Provider Types
import 'package:flutter_riverpod/flutter_riverpod.dart';
final greetingProvider = Provider<String>((ref) {
final name = ref.watch(userNameProvider);
return 'Hello, $name';
});
final counterProvider = StateProvider<int>((ref) => 0);
final usersProvider = FutureProvider<List<User>>((ref) async {
final api = ref.read(apiProvider);
return api.getUsers();
});
final messagesProvider = StreamProvider<List<Message>>((ref) {
return ref.read(chatServiceProvider).messagesStream;
});
Provider Type Reference
| Provider |
Use Case |
Provider |
Computed/derived values, dependency injection |
StateProvider |
Simple mutable state (counter, toggle) |
FutureProvider |
Async operations (one-time fetch) |
StreamProvider |
Real-time data streams |
NotifierProvider |
Complex state with methods |
AsyncNotifierProvider |
Async state with methods |
Notifier Pattern (Riverpod 2.0)
Synchronous Notifier
@riverpod
class TodoList extends _$TodoList {
@override
List<Todo> build() => [];
void add(Todo todo) {
state = [...state, todo];
}
void toggle(String id) {
state = [
for (final todo in state)
if (todo.id == id)
todo.copyWith(completed: !todo.completed)
else
todo,
];
}
void remove(String id) {
state = state.where((t) => t.id != id).toList();
}
}
Async Notifier
@riverpod
class UserProfile extends _$UserProfile {
@override
Future<User> build() async {
return ref.read(apiProvider).getCurrentUser();
}
Future<void> updateName(String name) async {
state = const AsyncValue.loading();
state = await AsyncValue.guard(() async {
final updated = await ref.read(apiProvider).updateUser(name: name);
return updated;
});
}
Future<void> refresh() async {
ref.invalidateSelf();
await future;
}
}
class TodoScreen extends ConsumerWidget {
const TodoScreen({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final todos = ref.watch(todoListProvider);
return ListView.builder(
itemCount: todos.length,
itemBuilder: (context, index) {
final todo = todos[index];
return ListTile(
key: ValueKey(todo.id),
title: Text(todo.title),
leading: Checkbox(
value: todo.completed,
onChanged: (_) => ref.read(todoListProvider.notifier).toggle(todo.id),
),
);
},
);
}
}
Selective Rebuilds with select
class UserAvatar extends ConsumerWidget {
const UserAvatar({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final avatarUrl = ref.watch(userProvider.select((u) => u?.avatarUrl));
return CircleAvatar(
backgroundImage: avatarUrl != null ? NetworkImage(avatarUrl) : null,
);
}
}
Async State Handling
class UserProfileScreen extends ConsumerWidget {
const UserProfileScreen({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final userAsync = ref.watch(userProfileProvider);
return userAsync.when(
data: (user) => UserProfileContent(user: user),
loading: () => const Center(child: CircularProgressIndicator()),
error: (err, stack) => ErrorView(
message: err.toString(),
onRetry: () => ref.invalidate(userProfileProvider),
),
);
}
}
Consumer for Scoped Rebuilds
class MyScreen extends StatelessWidget {
const MyScreen({super.key});
@override
Widget build(BuildContext context) {
return Column(
children: [
const Text('Static content'),
Consumer(
builder: (context, ref, child) {
final count = ref.watch(counterProvider);
return Text('Count: $count');
},
),
],
);
}
}
Provider Modifiers
@riverpod
class AutoDisposeExample extends _$AutoDisposeExample {
@override
String build() => 'value';
}
@riverpod
Future<User> userById(UserByIdRef ref, String id) async {
return ref.read(apiProvider).getUser(id);
}
final user = ref.watch(userByIdProvider('123'));
Best Practices
| Do |
Don't |
Use ref.watch() in build |
Use ref.watch() in callbacks |
Use ref.read() in callbacks |
Use ref.read() in build |
Use select() for granular rebuilds |
Watch entire state unnecessarily |
| Create new state instances |
Mutate state directly |
Use AsyncValue.guard() for errors |
Catch errors manually |
Quick Reference
| Method |
When to Use |
ref.watch() |
In build method, rebuilds on change |
ref.read() |
In callbacks, one-time read |
ref.listen() |
Side effects on change |
ref.invalidate() |
Force provider refresh |
ref.refresh() |
Invalidate and get new value |
Riverpod is an open-source state management library by Remi Rousselet.