riverpod-refs

Riverpod — Refs

Instructions

Ref (and WidgetRef in widgets) is how you interact with providers: read state, listen to changes, reset state, and register lifecycle callbacks. Providers get a Ref as the first parameter of their function or as this.ref in a Notifier. Widgets get a WidgetRef via Consumer / ConsumerWidget / ConsumerState.

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