Ref 01

Riverpod 3 API Cheat Sheet

Calculating reading time... • Module 1.5: Master Reference

⚡ Quick Reference Card Catalog

A one-page reference summary of every core Riverpod 3 API symbol, ref method, lifecycle hook, and container wrapper.

1. Core Ref Methods

API Symbol	Execution Context	Behavior & Contract	Example Usage
`ref.watch(provider)`	Inside widget `build()`	Subscribes reactively; triggers UI rebuild when state updates.	`final user = ref.watch(userProvider);`
`ref.read(provider)`	Button `onPressed` / Callbacks	One-time non-reactive read; does NOT subscribe to updates.	`ref.read(cartProvider.notifier).addItem(item);`
`ref.listen(p, fn)`	Inside widget `build()`	Executes side-effect callback on state change (Dialogs/Snackbars).	`ref.listen(authProvider, (prev, next) => navigate());`
`ref.invalidate(p)`	Anywhere (Callbacks / Providers)	Marks provider as stale immediately; re-fetches lazily when next read.	`ref.invalidate(shipmentListProvider);`
`ref.refresh(p)`	UI Pull-to-refresh handlers	Invalidates provider and forces immediate eager re-fetch.	`await ref.refresh(feedProvider.future);`
`ref.invalidateSelf()`	Inside Notifier methods	Forces notifier to re-execute its own `build()` method internally.	`ref.invalidateSelf();`
`ref.keepAlive()`	Inside Notifier `build()`	Prevents auto-disposal; keeps state cached in memory permanently.	`final link = ref.keepAlive();`
`ref.onDispose(fn)`	Inside Provider / Notifier	Registers cleanup callback executed when provider is destroyed.	`ref.onDispose(() => timer.cancel());`
`ref.mounted`	Async Notifier methods	Boolean check indicating whether notifier is still active in state graph.	`if (!ref.mounted) return;`

2. AsyncValue Cheat Sheet

Dart AsyncValue Pattern Quick Guide

// 1. UI Safe Pattern (.when)
asyncState.when(
  data: (items) => ListView(...),
  loading: () => const CircularProgressIndicator(),
  error: (err, stack) => Text('Error: $err'),
);

// 2. Controller Mutation Pattern (.guard)
state = const AsyncValue.loading();
state = await AsyncValue.guard(() async {
  return await repository.updateData();
});