riverpod

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.