---
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