Use setState for state that belongs to one widget, such as a selected tab or a text field. Use one package, Riverpod, Bloc or Provider, for state that several screens share, such as the signed-in user or a loaded list. All three are maintained, so pick one and keep it.
This guide is for developers choosing their first state management approach. Versions are from pub.dev in October 2026: flutter_riverpod 3.4.3, flutter_bloc 9.1.1, provider 6.1.5+1.
In short:
- Local state stays in the widget. Do not promote it to a global provider.
- Last releases: Riverpod September 2026, bloc core May 2026, provider August 2025.
- Riverpod 3 retries failed providers, which can hide errors behind a spinner.
- Prefer one package for shared app state when starting a new app.
Split state into ephemeral and app state
Flutter's docs separate ephemeral state from app state. Ephemeral state fits in one widget: the current page of a PageView, an animation's progress. App state is shared across screens and often outlives a restart: preferences, login, a shopping cart.
A StatefulWidget handles the first. A package earns its place on the second, and Flutter keeps a list of approaches with links to each.
The same counter in three packages
With plain setState, the number lives in the widget's State object and nothing else can read it. Here is the same counter once it has to be shared.
Provider wraps a ChangeNotifier. You call notifyListeners() after each change.
class CounterModel extends ChangeNotifier {
int count = 0;
void increment() { count++; notifyListeners(); }
}
// read: context.watch<CounterModel>().count
// act: context.read<CounterModel>().increment()
Riverpod keeps state in a Notifier, declared as a top-level provider.
final counterProvider = NotifierProvider<Counter, int>(Counter.new);
class Counter extends Notifier<int> {
@override
int build() => 0;
void increment() => state++;
}
// read: ref.watch(counterProvider)
// act: ref.read(counterProvider.notifier).increment()
Bloc uses a Cubit, which emits new states. A full Bloc adds event classes for a clear audit trail.
class CounterCubit extends Cubit<int> {
CounterCubit() : super(0);
void increment() => emit(state + 1);
}
// read: BlocBuilder<CounterCubit, int>(builder: (context, count) => ...)
For a counter, setState wins. Packages pay off when two screens need the same data, when data loads asynchronously, or when you want to test logic without drawing widgets.
Only Riverpod builds in loading and error states
All three let you test logic without drawing widgets, but only Riverpod wraps async data in a ready loading, data and error value (AsyncValue).
| Provider | Riverpod | Bloc | |
|---|---|---|---|
| State lives in | Widget tree | Top-level providers | Widget tree |
| Async data | Basic FutureProvider |
Built in | Your own states |
| Boilerplate | Low | Low | Medium |
Provider and Riverpod share an author, listed on pub.dev under the same publisher. Neither is deprecated.
Riverpod 3 retries failed providers
Riverpod 3 retries a failing provider with exponential backoff, as its 3.0 release notes explain. While it retries, AsyncValue.when shows the loading branch.
In our own Flutter app, we measured about 38 seconds of spinner before an error appeared. Check hasError before calling .when, and test with the network off.
GrowApps apps use Riverpod 3
In the GrowApps project template, pubspec.yaml depends on flutter_riverpod ^3.3.1 and main.dart wraps the app in a ProviderScope. The builder's rules tell the AI agents to write every provider by hand, with no code generation and no legacy StateNotifier. The architecture guidance keeps ephemeral state, such as a selected tab, in the widget.
Riverpod suits generated code because a top-level provider is easy to find and a test can swap it with ProviderScope(overrides: [...]). See how GrowApps builds an app.
Pick one in ten minutes
Write down which of your values are shared by two screens or more. If none, stay on setState.
If some, add one package and move just one of them, such as the signed-in user. Then read Flutter's app architecture guide and our project structure guide.