Reactive + caching. Part 1.

A reactive caching and state-management framework where you declare state as providers and widgets watch them to rebuild on change.

Declaration of state.

A globally-accessible, declarative piece of state (or computation) that widgets and other providers can watch.

Not found.

ProviderNotFoundException — provider's Provider.of<T>(context) looks up the tree at runtime; Riverpod references the provider object directly, so a missing one is a compile error.

No.

No — providers are top-level objects read via a ref, usable in other providers, pure Dart, and tests.

Same as provider.

The author of the provider package (Remi Rousselet) created Riverpod to fix provider's limitations — so it deliberately addresses those pain points.

Type count + context.

(1) Multiple providers of the same type. (2) Read/compose state without BuildContext. (Plus compile-time safety.)

Cells recompute.

Providers form a dependency graph like spreadsheet cells; a derived provider recomputes when an upstream value changes, and watchers update — automatic recalculation.

Boilerplate.

Same testability/separation, but Riverpod needs far less boilerplate than BLoC's events/states/mappers.

Compile-safe + testable.

Riverpod is compile-safe (explicit, checked dependencies, no hidden global magic) and easily testable in isolation, whereas GetX leans on global service-locator magic that's harder to test/reason about.

Compute once, reuse.

A provider computes its value once and caches it, recomputing only when a dependency changes or it's invalidated — and watchers react to those changes.

Provider + ConsumerWidget.

final msgProvider = Provider<String>((ref) => 'hi');
class S extends ConsumerWidget {
  const S({super.key});
  @override Widget build(c, ref) => Text(ref.watch(msgProvider));
}

Local only.

For tiny apps with purely local state where setState and a couple of constructors suffice — no shared/cached/derived state.

Unified.

Unified it into a single Ref type (removing FutureProviderRef, AutoDisposeRef, etc.), simplifying the API; the old compile-time checks became riverpod_lint rules.

Legacy import.

They became legacy — moved to a legacy import path and discouraged in favor of the modern Notifier/AsyncNotifier API (not removed, but signal "don't use for new code").

Failing providers.

Providers that fail during initialization automatically retry with exponential backoff by default (configurable per-provider via retry, or globally).

Like context.mounted.

To check, after an async gap, whether the provider is still alive before using ref — like BuildContext.mounted but for providers (if (!ref.mounted) return;).

Declaration vs state.

Providers are global declarations, but their state lives in a ProviderContainer you control and dispose. Two containers are isolated, so there's no shared mutable global — enabling clean tests and predictable behavior.

Refactor confidence.

In large apps, runtime lookup errors are easy to introduce and hard to catch; compile-time provider references mean refactors (renames, removals) surface as compile errors immediately, not as crashes in production.

flutter_. Part 2.

flutter_riverpod.

Core.

riverpod.

hooks_.

hooks_riverpod.

ProviderScope.

void main() => runApp(const ProviderScope(child: MyApp()));

Root.

Wrapping the topmost widget passed to runApp, above any widget that reads a provider.

"No ProviderScope".

Reading a provider throws "No ProviderScope found"; fix by wrapping the root widget in ProviderScope.

pub add.

flutter pub add flutter_riverpod.

custom_lint.

Riverpod-specific static analysis (misused ref.read/watch, missing deps, unhandled async). It runs via the custom_lint plugin.

analyzer plugins.

analyzer:
  plugins:
    - custom_lint

Former compile checks.

Riverpod 3.0 moved some former compile-time checks into the lint, so it's part of the safety story, not just style.

dart run.

dart run custom_lint

Re-export.

flutter_riverpod depends on and re-exports the core riverpod package, then adds Flutter bindings — one import gives you both.

Provider + watch.

final m = Provider<String>((ref) => 'It works!');
class Home extends ConsumerWidget {
  const Home({super.key});
  @override Widget build(c, ref) => Scaffold(body: Center(child: Text(ref.watch(m))));
}

Tooling.

Dev dependencies (dev_dependencies) — they're analysis tooling, not shipped in the app.

Redundant.

You shouldn't need to — flutter_riverpod re-exports riverpod. Adding both is redundant; just import flutter_riverpod.

Container ancestor.

Reading a provider resolves through the nearest ProviderScope's container; any reader with no ProviderScope ancestor has nowhere to resolve from and throws. Placing it at the root guarantees every reader is covered.

Declaration. Part 3.

No — it's a declaration. The 0 lives in a ProviderContainer once read.

Container.

A ProviderContainer that stores all provider state.

Store + dispose.

Stores provider state and the dependency graph; lazily initializes, caches, and disposes provider state.

ProviderContainer.

final c = ProviderContainer();
print(c.read(myProvider));
c.dispose();

Swap providers.

To replace specific providers with alternatives for that scope — Riverpod's DI and testing mechanism.

overrideWithValue.

ProviderScope(overrides: [apiProvider.overrideWithValue(FakeApi())], child: MyApp());

Isolated containers.

State lives in a container you create/dispose, so you can spin up an isolated ProviderContainer, override dependencies, read providers, and assert — no UI, no shared global state.

.test().

final container = ProviderContainer.test();

Subtree override.

A child container for a subtree that inherits from above but overrides specific providers just for that subtree.

Placeholder + override.

final prefsProvider = Provider<SharedPreferences>((ref) => throw UnimplementedError());
// main: ProviderScope(overrides: [prefsProvider.overrideWithValue(prefs)], child: MyApp());

Transparent fake.

Widgets keep watching the original provider but transparently receive the fake value, so real screens test against mocks with no code changes.

Lazy.

Lazily, the first time the provider is read/watched in a container — then its result is cached (recomputed on dependency change or invalidation).

Per container.

No — each container holds its own state for the provider. The declaration is shared; the state is per-container. (This isolation is why tests don't leak.)

overrideWith.

ProviderScope(overrides: [
  dataProvider.overrideWith((ref) => throw Exception('boom')),
], child: MyApp());

No prop drilling.

It avoids threading dependencies through many widget constructors ("prop drilling") and lets you swap implementations centrally (e.g. fakes in tests) without touching consumers.

Per-item state.

Providing per-item state in a list — each item's subtree overrides an "item" provider with its own value — or giving a section a different theme/config from the same declaration.

Resource cleanup.

To release the state and run providers' disposal logic (onDispose, subscriptions, timers). ProviderScope does this automatically; a hand-made container is your responsibility (or use ProviderContainer.test()).

container.read.

final c = ProviderContainer.test();
expect(c.read(fullNameProvider), 'Vivek Kumar');

New create fn.

overrideWith replaces the provider's create function (so the override can itself read other providers / build dynamic state), while overrideWithValue supplies a fixed value.

Owns the container.

It owns the ProviderContainer where all provider state lives and resolves; every read flows through it, and overrides defined on it shape what every provider resolves to.

Read-only. Part 4.

A read-only, cached value computed by its (ref) => ... create function.

Top-level final.

final answerProvider = Provider<int>((ref) => 42);

Extra ref.

Its build gets an extra WidgetRef ref parameter to read providers.

ref.watch.

@override Widget build(BuildContext c, WidgetRef ref) => Text('${ref.watch(answerProvider)}');

Subscribe.

Reads the value and subscribes, rebuilding the widget when it changes.

Narrow rebuilds.

A builder widget that gives a ref for just part of a tree, so only that part rebuilds when the provider changes — a performance tool.

builder.

Column(children: [
  const Header(),
  Consumer(builder: (c, ref, _) => Text(ref.watch(labelProvider))),
]);

ref + State.

When you need both a ref and the classic State lifecycle (initState, controllers, animations).

watch both.

final totalProvider = Provider<int>((ref) =>
  ref.watch(priceProvider) * ref.watch(quantityProvider));

Recompute.

watch makes the provider recompute when the dependency changes; read would only grab a one-time value and never react.

watch the client.

final apiClientProvider = Provider((ref) => ApiClient());
final userRepoProvider = Provider((ref) => UserRepository(ref.watch(apiClientProvider)));

Shared, overridable.

It exposes a single cached instance that everything depends on via ref.watch, and it's overridable for tests — DI without a service locator.

Lazy + cached.

Lazily on first read; once, then cached — re-running only if a watched dependency changes or it's invalidated.

Same provider.

// Both read the same cached instance from the container:
Widget a(WidgetRef ref) => Text(ref.watch(userRepoProvider).name);
Widget b(WidgetRef ref) => Text(ref.watch(userRepoProvider).id);

Both get the identical shared UserRepository.

Smaller subtree.

ref.watch rebuilds the watcher; if the whole widget watches, the whole subtree rebuilds. Wrapping only the dependent part in a Consumer limits rebuilds to that small subtree, leaving expensive siblings untouched (Flutter Part 4).

Graph propagation.

If firstNameProvider changes, fullNameProvider (which ref.watches it) recomputes; every widget ref.watching fullNameProvider then rebuilds — the change propagates down the dependency graph.

Immutable declaration.

The global is an immutable declaration with no mutable state; the mutable state lives per-container. So the global can't be a source of shared-mutable-state bugs.

ConsumerState.

class S extends ConsumerStatefulWidget { const S({super.key});
  @override ConsumerState<S> createState() => _S(); }
class _S extends ConsumerState<S> {
  final c = TextEditingController();
  @override void dispose(){ c.dispose(); super.dispose(); }
  @override Widget build(ctx){ final v = ref.watch(myProvider); return Text('$v'); }
}

Stale derived.

It could compile, but the derived value would be computed once and never update when the sources change — a stale derived provider. Use ref.watch for dependencies.

Widget vs provider.

WidgetRef is the ref given to widgets (via ConsumerWidget/Consumer/ConsumerState) to read providers. A provider's create function gets a Ref (unified in 3.0). Both offer watch/read/listen; WidgetRef is the widget-side handle into the same container.

Override the input.

final c = ProviderContainer.test(overrides: [
  firstNameProvider.overrideWithValue('Ada'),
]);
expect(c.read(fullNameProvider), 'Ada Kumar');

Overriding the input flows through the graph to the derived provider.

Declare/watch/render.

Declare a provider, ref.watch it in a ConsumerWidget, render the value — and the widget rebuilds automatically when the provider changes.

Subscribe. Part 5.

Reads + subscribes; the watcher rebuilds/recomputes on change. Use in build and provider create functions.

Once.

Reads the current value once with no subscription. Use in callbacks/lifecycle.

Side effect.

Runs a side-effect callback when a provider changes (with previous/next), without rebuilding the widget.

reflect/act/react.

watch = reflect (display), read = act (callbacks), listen = react (side effects).

watch in build.

Text('${ref.watch(counterProvider)}')

read .notifier.

onPressed: () => ref.read(counterProvider.notifier).increment(),

Act, not subscribe.

A callback should act, not subscribe; watch in a callback would try to create a subscription each call (wrong, lint-flagged). read grabs the current value/notifier.

watch.

Widget build(c, ref) => Text('${ref.watch(counterProvider)}');

read doesn't subscribe → frozen UI; watch rebuilds on change.

No subscription.

No subscription means no rebuild on change; the displayed value goes stale. Displayed values must use watch.

listen.

ref.listen<String?>(errorProvider, (prev, next) {
  if (next != null) ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(next)));
});

Transition.

(previous, next) — letting you react to specific transitions (e.g. loading→error).

build.

In build (tied to the widget lifecycle); it runs the callback on change without rebuilding.

listen + is AsyncData.

ref.listen(checkoutProvider, (prev, next) {
  if (next is AsyncData) Navigator.of(context).pushNamed('/success');
});

build runs often.

build runs many times unpredictably (Flutter Part 4), so side effects there fire repeatedly/at wrong times. ref.listen runs them only on actual change.

display/callback.

(1) In build, never read a displayed value — use watch. (2) In callbacks, never watch — use read.

Outside build.

To listen outside build (e.g. in initState); it returns a subscription you must close yourself, unlike ref.listen which is managed by build.

Auto-pause.

Riverpod auto-pauses them (via TickerMode) so side effects don't fire for invisible widgets; they resume when visible again (pause/resume support).

display/act/react.

final total = ref.watch(cartTotalProvider);                 // display
ref.listen(checkoutProvider, (p, n) { if (n is AsyncData) go(); }); // react
// onPressed: () => ref.read(cartProvider.notifier).checkout();      // act

Caller doesn't subscribe.

You're invoking an action from a callback; the caller doesn't need to subscribe (it's not displaying the notifier). Widgets that display the resulting state watch the provider separately and rebuild.

Depend vs act.

Yes: use ref.watch in the build/create to establish a reactive dependency (recompute on change), and ref.read inside notifier methods (event-handler-like actions) to grab a value/notifier without re-subscribing. Same display/act split, inside a provider.

Mutate in build.

Mutating state during build (e.g. calling a notifier method) while watching it triggers a rebuild, which mutates again → loop. Move mutations to callbacks/ref.listen/lifecycle, never build.

watch + listen.

ref.watch to display it (rebuild) and ref.listen to run the side effect on change — they coexist in the same build.

Likely a bug.

Because read in build is usually a mistake (stale UI) — the lint nudges you to use watch for displayed values, catching the bug as you type.

Three verbs.

Display/derive → watch; act in a callback → read; side effect on change → listen.

final msg = Provider<String>((ref) => 'Hello');
class Home extends ConsumerWidget {
  const Home({super.key});
  @override
  Widget build(BuildContext c, WidgetRef ref) =>
      Scaffold(body: Center(child: Text(ref.watch(msg))));
}

final priceProvider = Provider((ref) => 10);
final qtyProvider = Provider((ref) => 3);
final totalProvider = Provider((ref) => ref.watch(priceProvider) * ref.watch(qtyProvider));
// build: Text('${ref.watch(totalProvider)}'); // 30

final loggerProvider = Provider((ref) => Logger());
final serviceProvider = Provider((ref) => Service(ref.watch(loggerProvider)));

await tester.pumpWidget(ProviderScope(
  overrides: [repoProvider.overrideWithValue(FakeRepo(name: 'Test'))],
  child: const MyApp(),
));
expect(find.text('Test'), findsOneWidget);

Column(children: [
  const ExpensiveHeader(),
  Consumer(builder: (c, ref, _) => Text(ref.watch(labelProvider))),
]);

Only the label rebuilds on change.

final prefsProvider = Provider<SharedPreferences>((ref) => throw UnimplementedError());
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final prefs = await SharedPreferences.getInstance();
  runApp(ProviderScope(overrides: [prefsProvider.overrideWithValue(prefs)], child: const MyApp()));
}

Text('${ref.watch(counterProvider)}'),                    // display
onPressed: () => ref.read(counterProvider.notifier).inc(), // act

ref.listen(formProvider, (prev, next) {
  if (next is AsyncError) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('${next.error}')));
  }
});

final c = ProviderContainer.test(overrides: [
  priceProvider.overrideWithValue(5),
  qtyProvider.overrideWithValue(4),
]);
expect(c.read(totalProvider), 20);

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

// A tiny notifier holding the name (full Notifier coverage is Series 2).
class NameNotifier extends Notifier<String> {
  @override
  String build() => 'Vivek';
  void setName(String n) => state = n;
}
final nameProvider = NotifierProvider<NameNotifier, String>(NameNotifier.new);

// Derived greeting depends on the name.
final greetingProvider = Provider<String>((ref) {
  final name = ref.watch(nameProvider);
  return 'Hello, $name!';
});

class GreetingScreen extends ConsumerWidget {
  const GreetingScreen({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final greeting = ref.watch(greetingProvider);            // WATCH: display

    ref.listen<String>(nameProvider, (prev, next) {          // LISTEN: side effect
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Name changed to $next')),
      );
    });

    return Scaffold(
      appBar: AppBar(title: const Text('Greeting')),
      body: Center(child: Text(greeting, style: const TextStyle(fontSize: 28))),
      floatingActionButton: FloatingActionButton(
        onPressed: () =>                                       // READ: act
            ref.read(nameProvider.notifier).setName('Dash'),
        child: const Icon(Icons.edit),
      ),
    );
  }
}

void main() => runApp(const ProviderScope(child: MaterialApp(home: GreetingScreen())));

// A pure-Dart-style test of the derived provider with an override:
// final c = ProviderContainer.test(overrides: [nameProvider]); // (override the notifier if needed)
// expect(c.read(greetingProvider), 'Hello, Vivek!');

This single screen exercises the whole Foundation series: ProviderScope at the root (Part 3); a derived Provider and a ConsumerWidget (Part 4); and watch (display), read (act on tap), and listen (snackbar side effect) all in one build (Part 5). The Notifier is a preview of Series 2 — you now have everything you need to dive into provider types.