/riverpod

name: riverpod
description: "Use when working with Flutter Riverpod state management. Covers providers, consumers, refs, containers, overrides, async state, code generation, testing, and safe defaults."
metadata:
  revision: 1
  updated-on: "2026-04-04"
  source: official
  tags: "flutter,dart,riverpod,flutter_riverpod,providers,async,testing,codegen"

Flutter Riverpod State Management

Use this skill when building Flutter state management with `riverpod` and `flutter_riverpod`.

Core Rule

• Use `Provider` for read-only values and dependency wiring.
• Use `StateProvider` for small mutable state.
• Use `FutureProvider` for one-shot async loading.
• Use `StreamProvider` for reactive streams.
• Use `Notifier` or `AsyncNotifier` for feature state that needs mutation methods.
• Use `autoDispose` for short-lived state.
• Use `family` when provider output depends on an argument.
• Use `flutter_riverpod` in Flutter apps.
• If you use `flutter_riverpod`, you usually do not add `riverpod` separately because the Flutter package brings it in transitively.
• Current stable line is Riverpod 3.x (`riverpod` 3.2.1, `flutter_riverpod` 3.3.1).

Decision Guide

Choose Riverpod when:

• you want provider-based dependency injection and reactive state in one model
• state should be derived from other providers
• async data is a major part of the feature
• test overrides and scoped state matter
• you want fewer classes than a Bloc-heavy approach

Choose a different pattern when:

• the feature is a tiny local state toggle and a simple widget would be enough
• the logic is better expressed as an explicit event machine

Required Project Setup

For Dart-only code:

• add `riverpod`

For Flutter UI code:

• add `flutter_riverpod`
• wrap the app in `ProviderScope`
• use `ConsumerWidget`, `Consumer`, or `ConsumerStatefulWidget` where `ref` is needed

If code generation is used:

• add `riverpod_annotation`
• add `riverpod_generator`
• add `build_runner`

Implementation Pattern

Prefer this structure:

• providers own state, dependencies, and derived values
• repositories and APIs stay outside widgets
• UI reads state with `ref.watch`
• UI performs imperative reads with `ref.read`
• container-level overrides are used for tests, demos, and environment-specific wiring

Keep providers small and composable. Keep state immutable unless the provider type is specifically meant for mutation. Keep feature logic in providers or notifiers, not in widgets.

Lifecycle Rules

• Use `autoDispose` for short-lived screens and transient queries.
• Use `ref.keepAlive()` only when you want cached state to survive temporarily.
• Prefer provider disposal over manual cleanup.
• In tests and pure Dart code, dispose `ProviderContainer` when finished.

UI Binding Rules

Use `ConsumerWidget` when the whole widget depends on providers. Use `Consumer` when only a small subtree needs access to `ref`. Use `ConsumerStatefulWidget` when you need widget lifecycle plus `ref`. Use `select` to reduce rebuilds. Use `ProviderListener` or `ref.listen` for side effects.

Testing Rules

• Test providers through `ProviderContainer`.
• Override dependencies instead of mocking provider internals.
• Assert `AsyncValue` states directly for async providers.
• Dispose containers in tests.

Common Pitfalls

• Do not call `ref.watch` inside callbacks; use `ref.read` there.
• Do not skip `ProviderScope` at the app root.
• Do not use `StateProvider` for large feature state.
• Do not put business logic in widgets.
• Do not rebuild the whole tree when a single field changes; use `select`.
• Do not model async loading manually when `FutureProvider` or `AsyncNotifier` fits.
• Do not forget provider overrides for tests and previews.

What To Prefer In Answers

When writing code or advising on design:

• show the smallest working provider first
• mention whether `ProviderScope` is required
• mention whether the provider should be `autoDispose` or cached
• mention whether a `family` is needed for arguments
• include test override notes when dependencies are external
• keep examples aligned with the current Riverpod docs and Flutter integration patterns
• if code generation is involved, prefer matching `riverpod_annotation` / `riverpod_generator` versions from the same 3.x release line

Minimal Reference Checklist

• `ProviderScope` = app root setup
• `ref.watch` = rebuild on change
• `ref.read` = imperative access
• `select` = narrower rebuilds
• `autoDispose` = short-lived state
• `family` = parameterized provider
• `ProviderContainer` = test/headless container