flutter-riverpod-pattern
Implements state management in Flutter applications using Riverpod 3.x and Code Generation.
SKILL.mdskills/flutter/riverpod/SKILL.md
GitHubFlutter Riverpod Pattern (3.x)
Context
Apply when creating or modifying state management using Riverpod in Flutter projects. We use Riverpod 3.x with code generation (riverpod_annotation).
3.0 Migration:
AutoDisposeNotifier,FamilyNotifier, and per-providerRefsubclasses (ExampleRef,FutureProviderRef) are removed — useNotifierandRefeverywhere.StateProvider/StateNotifierProvider/ChangeNotifierProvidermoved topackage:riverpod/legacy.dart.
Instructions
- Code Generation: Always use
@riverpodandriverpod_annotation. Never manually writeProvider,FutureProvider, etc. - State classes: Use
freezedfor complex states, orAsyncValuefor async operations. - Naming: Class
FeatureNameextending_$FeatureName, filefeature_name_provider.dart. - File structure:
feature_name/ ├── providers/ │ └── feature_name_provider.dart ├── pages/ │ └── feature_name_page.dart └── widgets/ └── ... - Never put business logic in widgets — delegate to Notifiers.
- Use
ConsumerWidgetorConsumerStatefulWidget. - Error handling: Use
AsyncValue.guard()for async error handling. - Unified Ref: Always use
Refin code-gen — notExampleRefor typed variants.@riverpod Example example(Ref ref) => Example(); // ✅ 3.x // Example example(ExampleRef ref) => Example(); // ❌ 2.x removed
Provider Lifecycle
Global Singleton (keepAlive: true)
@Riverpod(keepAlive: true)
class UserRepository extends _$UserRepository {
@override
FutureOr<void> build() { /* init */ }
}
autoDispose (Default)
@riverpod
class TaskList extends _$TaskList {
@override
FutureOr<List<Task>> build() async {
return ref.watch(userRepositoryProvider.notifier).fetchTasks();
}
}
Ref.mounted — Safety after async gaps
Riverpod 3.0 throws if you interact with a disposed Ref/Notifier. Always check after async:
Future<void> addTodo(String title) async {
final newTodo = await api.addTodo(title);
if (!ref.mounted) return; // Must check after await
state = [...state, newTodo];
}
Automatic Retry
Providers auto-retry on failure (200ms exponential backoff up to 6.4s). Configure globally or per-provider:
// Global
ProviderScope(
retry: (retryCount, error) {
if (error is ProviderException) return null;
if (retryCount > 5) return null;
return Duration(seconds: retryCount * 2);
},
child: MyApp(),
);
// Per-provider
Duration? myRetry(int retryCount, Object error) => retryCount > 3 ? null : Duration(seconds: retryCount * 2);
@Riverpod(retry: myRetry)
class TodoList extends _$TodoList {
@override
List<Todo> build() => [];
}
Mutations (Experimental)
React to side-effects with loading/success/error states. Prevents disposal during in-flight operations:
final addTodoMutation = Mutation<void>();
class AddTodoButton extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final addTodo = ref.watch(addTodoMutation);
return switch (addTodo) {
MutationIdle() => ElevatedButton(
onPressed: () => addTodoMutation.run(ref, (tsx) async {
await tsx.get(todoListProvider.notifier).addTodo('New Todo');
}),
child: const Text('Submit'),
),
MutationPending() => const CircularProgressIndicator(),
MutationError() => const Text('Failed'),
MutationSuccess() => const Text('Done!'),
};
}
}
Use
tsx.get()instead ofref.read()— keeps provider alive until mutation completes.
Offline Persistence (Experimental)
@riverpod
@JsonPersist()
class TodosNotifier extends _$TodosNotifier {
@override
FutureOr<List<Todo>> build() async {
persist(ref.watch(storageProvider.future));
return await fetchTodos();
}
}
AsyncValue (Sealed in 3.0)
Exhaustive pattern matching, renamed valueOrNull → value, progress support:
return switch (ref.watch(myProvider)) {
AsyncData(:final value) => Text('$value'),
AsyncError(:final error) => Text('Error: $error'),
AsyncLoading(:final progress) => LinearProgressIndicator(value: progress),
};
AsyncValue.isFromCache— true when from offline persistenceAsyncLoading(progress: 0.5)— optional progress reporting
Form Management (Reactive Forms)
When handling forms, encapsulate the FormGroup within the Action Notifier. This keeps validation logic out of the UI and ensures the form state is disposed of correctly.
Implementation Pattern
- Initialize: Create the
FormGroupin thebuild()method. - Dispose: Register
form.disposeinref.onDispose. - Validate: Perform validation before executing side effects.
- Access: Retrieve values directly from the form controls.
@riverpod
class LoginNotifier extends _$LoginNotifier {
late final FormGroup form;
@override
FutureOr<void> build() {
form = fb.group({
'email': ['', Validators.required, Validators.email],
'password': ['', Validators.required],
});
// Ensure form is disposed when provider is disposed
ref.onDispose(form.dispose);
}
Future<void> login() async {
if (form.invalid) {
form.markAllAsTouched();
return;
}
state = const AsyncValue.loading();
// Use form.control('name').value to get data
final result = await ref.read(authRepositoryProvider).login(
email: form.control('email').value,
password: form.control('password').value,
);
// ... handle result
}
}
UI Performance & Optimization
1. Selective Rebuilds (ref.select)
final name = ref.watch(userProvider.select((u) => u.name)); // Only rebuilds on name change
2. Granular Rebuilds (Consumer)
Consumer(
builder: (context, ref, child) {
final themeMode = ref.watch(settingsProvider.select((s) => s.themeMode));
return Text('Current mode: $themeMode');
},
)
3. Side Effects (ref.listen)
ref.listen(authProvider, (previous, next) {
if (next is AsyncError) {
ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('$next')));
}
});
4. Pause/Resume & Weak Listeners
Invisible widget listeners are auto-paused via TickerMode. Manual control:
final sub = ref.listen(provider, (prev, next) {});
sub.pause();
sub.resume();
// Weak: listen without preventing auto-dispose
ref.listen(provider, weak: true, (prev, next) {});
5. List Optimization (Family)
@riverpod
Task individualTask(Ref ref, String taskId) {
return ref.watch(taskListProvider).value!.firstWhere((t) => t.id == taskId);
}
// Widget: ref.watch(individualTaskProvider(id))
Testing
// Auto-disposing container
final container = ProviderContainer.test();
// Mock only build method
myProvider.overrideWithBuild((ref) => 42);
// Override with value
myFutureProvider.overrideWithValue(AsyncValue.data(42));
// Widget test container access
ProviderContainer container = tester.container();
Anti-patterns
- ❌ Watching global state without
.select - ❌ Business logic in
build()— use computed providers - ❌ Missing
constconstructors for static widgets - ❌ Passing
WidgetRefto child widgets — useConsumer - ❌ Using
setStatefor provider-managed data - ❌ Using legacy providers (
StateProvider, etc.) in new code - ❌ Using typed Ref (
ExampleRef) — useRef - ❌ Ignoring
ref.mountedafter async gaps