Riverpod — Refs

Instructions

Ref

this.ref

Obtaining a Ref

• Inside a provider: First parameter of the provider function, or

  ref

  property in a Notifier.
• Inside a widget: Use a Consumer (builder gives

  ref

  ), ConsumerWidget (

  build(context, ref)

  ), or ConsumerStatefulWidget (state has

  ref

  ). Pass

  ref

  to other functions if needed.

Listening to state

• ref.watch(provider) — Declarative. Your widget/provider rebuilds when the provider changes. Use this by default in build methods.
• ref.listen(provider, (prev, next) { ... }) — Imperative. Run side effects when the provider changes (e.g. show a dialog, navigate). Safe to use in build; for initState use

  ref.listenManual

  and manage the subscription.

// In a widget
final tick = ref.watch(tickProvider);
return Text('Tick: $tick');

// Side effect when provider changes
ref.listen(tickProvider, (previous, next) {
  print('Tick changed from $previous to $next');
});

Reading without listening

• ref.read(provider) — Get current value without subscribing. Use in event handlers (e.g. onPressed), not to "optimize" by avoiding watch. For selective rebuilds use

  ref.watch(provider.select((value) => ...))

  .

onPressed: () {
  final tick = ref.read(tickProvider);
  print('Current tick: $tick');
}

Resetting state

• ref.invalidate(provider) — Discard current state; provider will recompute on next read. If the provider is listened to, a new state is created.
• ref.refresh(provider) — Same as invalidate + read: invalidates and returns the new value. Use when you need the new value immediately.

ref.invalidate(tickProvider);
// or
final newTick = ref.refresh(tickProvider);

Lifecycle: onDispose, onCancel

• ref.onDispose(callback) — Called when the provider state is destroyed (e.g. auto-dispose or recomputation). Use to close StreamControllers, cancel timers, etc. Do not trigger side effects that modify other providers inside onDispose.
• ref.onCancel(callback) — Called when the last listener is removed (before dispose). ref.onResume(callback) — Called when a listener is added again after onCancel.

final provider = StreamProvider<int>((ref) {
  final controller = StreamController<int>();
  ref.onDispose(controller.close);
  return controller.stream;
});