Riverpod 3.0 Highlights: Auto‑Retry, Pause/Resume, and Simplified API

In a previous article we discussed Riverpod 2.x design and the upcoming 3.0 refactor; with the release of Riverpod 3.0 many detailed changes have arrived.

Of course, this also brings usage changes.

Below is a comparison of Riverpod 3.0 vs 2.0, highlighting new features:

Automatic retry of failed providers: When a provider fails (e.g., network error), Riverpod automatically retries the computation until it succeeds.

Pause/Resume support: Listeners associated with a widget are automatically paused when the widget is off‑screen.

Experimental offline and mutation support: Provides offline caching and a structured way to handle asynchronous actions such as form submissions.

Simplified API: Merges AutoDisposeNotifier and Notifier interfaces for a more unified and concise API.

Riverpod 3.0 also introduces several breaking changes:

Migration of traditional providers: StateProvider, StateNotifierProvider and ChangeNotifierProvider are moved to a legacy import path; the new Notifier API is recommended.

Unified update filtering with == : All providers now use equality comparison instead of identical to decide whether to rebuild.

Simplified Ref and removed subclasses: The generic Ref type is now used universally, and many specialized subclasses have been removed.

ProviderObserver signature change: The observer now receives a single ProviderObserverContext object instead of separate parameters.

We will now explain these changes in detail.

Automatic Retry of Failed Providers

In Riverpod 3.0 a provider automatically retries failed calculations, meaning transient errors such as network glitches will not immediately throw but will be recomputed until successful.

This feature is enabled by default, but you can disable or customize it globally or per provider.

Global disable/customize: Set the retry parameter on ProviderScope or ProviderContainer to control retry logic.

Per‑provider disable/customize: Provide a retry callback when defining the provider.

Pause/Resume Support

To optimise resource usage, Riverpod 3.0 automatically pauses listeners when the associated widget is off‑screen. This behaviour is enabled by default and can be manually controlled with Flutter’s TickerMode widget.

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return TickerMode(
      enabled: false, // Pauses listeners
      child: Consumer(
        builder: (context, ref, child) {
          // This watch will be paused
          final value = ref.watch(myProvider);
          return Text(value.toString());
        },
      ),
    );
  }
}

Offline and Mutation Support (Experimental)

Riverpod 3.0 adds two experimental features:

Offline support: Easily persist provider state for restoration after app restart or when offline.

Mutation support: Provides a structured way to handle asynchronous operations such as login or form submission.

// A mutation to track the "add todo" operation.
final addTodo = Mutation<Todo>();

// Listen to the current state of the mutation.
final addTodoState = ref.watch(addTodo);

switch (addTodoState) {
  case MutationIdle():
    // Show a button to add a todo
    break;
  case MutationPending():
    // Show a loading indicator
    break;
  case MutationError():
    // Show an error message
    break;
  case MutationSuccess():
    // Show the created todo
    break;
}

API Changes

Riverpod 3.0 dramatically simplifies and unifies its core API.

1. Merge AutoDispose interfaces

Previously many interfaces carried the AutoDispose prefix (e.g., AutoDisposeProvider, AutoDisposeNotifier). In 3.0 they are unified; you now use Provider or Notifier with an isAutoDispose flag.

// V2.0
final myProvider = Provider.autoDispose((ref) {
  return MyObject();
});

// V3.0
final myProvider = Provider(
  (ref) => MyObject(),
  isAutoDispose: true,
);

2. Remove FamilyNotifier variants

Family variants such as FamilyNotifier and FamilyAsyncNotifier are removed. Use Notifier or AsyncNotifier with constructor arguments instead.

final provider = NotifierProvider.family<CounterNotifier, int, String>(CounterNotifier.new);
class CounterNotifier extends Notifier<int> {
  CounterNotifier(this.arg);
  final String arg;

  @override
  int build() {
    // Use arg here
    return 0;
  }
}

3. Provider changes

StateProvider

, StateNotifierProvider and ChangeNotifierProvider are now considered legacy. The new Notifier, AsyncNotifier and StreamNotifier APIs replace them. Notifier: Replaces StateNotifierProvider for synchronous state. AsyncNotifier: Replaces StateNotifierProvider or FutureProvider for asynchronous state. StreamNotifier: Replaces StreamProvider.

4. Unified == for update filtering

All providers now use equality comparison ( ==) to decide whether the state has changed, providing consistent rebuild behaviour.

5. Simplified Ref and removed subclasses

The generic Ref type is now used for all providers, eliminating the need to remember different subclass names and improving type safety.

6. ProviderObserver interface change

The observer now receives a ProviderObserverContext containing the provider, container, and other information, instead of separate parameters.

class MyObserver extends ProviderObserver {
  @override
  void didAddProvider(ProviderObserverContext context, Object? value) {
    print('Provider ${context.provider.name ?? context.provider.runtimeType} was created');
  }
}

Overall, Riverpod 3.0 focuses on simplifying the API, improving consistency, and adding powerful features such as automatic retry, offline caching, and mutation support while keeping the annotation mode compatible.

Do you like Riverpod 3.0?