• Fix the IDE pausing on "markNeedsBuild" exceptions when checking "pause on all exceptions".
• ConsumerWidget's now uses the TickerMode notifier instead of TickerMode.of to avoid unnecessary rebuilds when widgets are hidden (thanks to @Colton127)
• Added missing weak flags to WidgetRef.listen/listenManual
• Added Ref.isPaused to check if there are any active/non-paused listeners.
• Deprecated family.overrideWith in favour of family.overrideWith2 The behaviour is the same, but the callback now takes the argument as a parameter. In 4.0.0, overrideWith2 will be renamed to overrideWith.
• Fix a regression that caused Notifiers to lose their state when one of their dependencies changed. (thanks to @yegair)
• Fixed ref.mounted returning true for stale refs after provider rebuild, causing race conditions in async providers.
• Fixed a bug where providers with only weak listeners (ref.listen(..., weak: true)) would incorrectly initialize during hot reload (thanks to @tguerin)
• Fixes selectAsync sometimes throwing an exception when unsubscribed to.

Dependency changes #

• riverpod upgraded to 3.2.0

• Added an alternative way to combine asynchronous providers. This can be done by using AsyncValue.requireValue inside FutureProvider/AsyncNotifier like so:

  final sumProvider = FutureProvider((ref) { // Not async
    AsyncValue<int> a = ref.watch(aProvider);
    AsyncValue<int> b = ref.watch(bProvider);
  
    // The following is safe if used inside the init function of providers.
    return a.requireValue + b.requireValue;
  })
  

  This enables synchronously combining asynchronous providers.

  See AsyncValue.requireValue

• Fixed a bug with scoping when specifying dependencies: [...]

• Added Override.origin. This enables knowing which provider is associated with an override.

• Fix a regression with AsyncLoading.isRefreshing/isReloading

• riverpod upgraded to 3.0.3

Fixed an assertion error when a ProviderContainer is linked to two different UncontrolledProviderScope

• ChangeNotifierProviderFamily is now correctly accessible in package:flutter_riverpod/legacy.dart instead of /misc.dart
• Now supports Dart 3.7.0

Finally, a stable release for Riverpod 3.0!

For the full changelog, check out https://riverpod.dev/docs/whats_new

• A provider that is currently being retried is now flagged as "loading" while the retry attempts complete. Meaning that ref.watch(provider.future) skips the intermediate error states.
• Fix an issue with the internals of AsyncValue
• ProviderObserver is now marked with base
• Fix provider rebuild order issue.
• Fix "Tried to refresh x multiple times in the same frame" incorrectly triggering.
• Removed FamilyNotifier and variants, in favour of Notifier.
• Preserve persisted state if a provider throws.
• provider.future will now skip offline-persisted state by default. This avoids awkward unexpected provider rebuild when chaining persisted providers.
• Made Mutation.call generic. This allows for better compatibility with generic-returning functions (thanks to @TekExplorer)

• Added MutationState.isPending/isIdle/hasError/isSuccess
• fixes various "pause" issues
• Bump minimum meta version
• Added AsyncValue.retrying, to check when a retry is scheduled or pending
• Exposed the default retry implementation (ProviderContainer.defaultRetry)
• Offline's Storage now is base and requires overriding deleteOutOfDate
• Make AsyncValue.copyWithPrevious @internal. This API was not meant to be public.

• Reworked mutations to work without code-generation
• Added Async/SyncProviderTransformerMixin. Those enable making custom ProviderListenables using a reasonably simple syntax. For instance, you could implement your own provider.select
• Added AsyncResult. This is an interface shared between AsyncData and AsyncError, but not AsyncLoading.
• Revert Notifier life-cycle change. They are once again preserved across rebuilds.
• Provider errors are now reported to the ProviderContainer's Zone instead of whatever last used the provider.
• Breaking: When a ref.watch/ref.read rethrows an error, the error is now wrapped in a ProviderException.
• Use TickerMode instead of Visibility for pausing out-of-view widgets
• Reworked offline to simplify its usage
• Added widget test helper to find a ProviderContainer in the widget tree: tester.container() (thanks to @Luckey-Elijah)

• riverpod upgraded to 3.0.0-dev.15

• riverpod upgraded to 3.0.0-dev.14

• riverpod upgraded to 3.0.0-dev.13

Say hello to Riverpod 3.0.0! This major version is a transition version, to unblock the development of the project. It is quite possible that a 4.0.0 will be released relatively soon in the future, so keep that in mind when migrating.

Here are some highlights about this version:

• Offline and mutation support, as experimental features
• Automatic retry support
• Pause/resume support
• Simplification of various aspects of the API (such as fusing AutoDisposeNotifier/Notifier)
• Added a Ref.mounted to simplify dealing with provider disposal
• Improved testing with the new ProviderContainer.test() and the ability to mock a Notifier's build method without mocking the whole object using provider.overrideWithBuild(...)

Note about experimental features: Anything imported with package:riverpod/experimental/....dart are not stable features. They may be modified in breaking ways without a major version. Use with care!

Full change list #

• Breaking: ChangeNotifierProvider, StateProvider and StateNotifierProvider are moved out of package:hooks_riverpod/hooks_riverpod.dart to package:hooks_riverpod/legacy.dart.
• Failing providers are now automatically retried after a delay. The delay can be optionally configured.
• Allow using Ref synchronously after a provider has been invalidated. This avoids mounted exceptions when doing multiple operations in a quick succession.
• Breaking: All providers now use == to compare previous/new values and filter updates. If you want to revert to the old behavior, you can override updateShouldNotify inside Notifiers.
• Instead of Provider.autoDispose() and Provider.autoDispose.family(), it is now possible to write Provider(isAutoDispose: true) and Provider.family(isAutoDispose: true).
• Breaking: ProviderListenable.addListener is deleted and now internal-only. A simpler alternative will be added in the future.
• Breaking: ProviderObserver methods have been updated to take a ProviderObserverContext parameter. This replaces the old provider+container parameters, and contains extra information.
• Breaking: Removed all Ref subclasses (such FutureProviderRef). Use Ref directly instead. For FutureProviderRef.future, migrate to using an AsyncNotifier.
• Breaking All ref and notifier methods besides "mounted" now throw if used after getting disposed.
• Breaking: StateProvider and StateNotifierProvider are moved out of package:flutter_riverpod/flutter_riverpod.dart to package:flutter_riverpod/legacy.dart.
• Breaking Some internal utils are no-longer exported.
• Breaking AsyncValue.value now returns null during errors.
• Breaking removed AsyncValue.valueOrNull (use .value instead).
• Stream/FutureProvider.overrideWithValue was added back.
• Breaking: Notifier and variants are now recreated whenever the provider rebuilds. This enables using Ref.mounted to check dispose.
• Breaking: StreamProvider now pauses its StreamSubscription when the provider is not actively listened.
• Breaking: Calling ref.watch multiple times calls ref.onListen every-times.
• Breaking: A provider is now considered "paused" if all of its listeners are also paused. So if a provider A is watched only by a provider B, and B is currently unused, then A will be paused.
• Breaking: When an asynchronous provider rebuilds, it doesn't immediately stops listening to its previous providers. Instead, those subscriptions are removed when the rebuild completes. This impacts how "auto-dispose" behaves. See https://github.com/rrousselGit/riverpod/issues/1253
• Fix StreamProvider not cancelling the StreamSubscription if the stream is never emitted any value.
• All Ref life-cycles (such as Ref.onDispose) and Notifier.listenSelf now return a function to remove the listener.
• Added methods to ProviderObserver for listening to "mutations". Mutations are a new code-generation-only feature. See riverpod_generator's changelog for more information.
• Added Ref.listen(..., weak: true). When specifying weak: true, the listener will not cause the provider to be initialized. This is useful when wanting to react to changes to a provider, but not trigger a network request if not necessary.
• AsyncValue now has an optional progress field. This can be set by providers to allow the UI to show a custom progress logic.
• An error is now thrown when trying to override a provider twice in the same ProviderContainer.
• Disposing a ProviderContainer now disposes of all of its sub ProviderContainers too.
• Added ProviderSubscription.pause()/.resume(). This enables temporarily stopping the subscription to a provider, without it possibly loosing its state when using autoDispose.
• Added ProviderContainer.test(). This is a custom constructor for testing purpose. It is meant to replace the createContainer utility.
• Added NotifierProvider.overrideWithBuild, to override Notifier.build without overriding methods of the notifier.
• Ref.mounted has been added. It can now be used to check if a provider was disposed.
• When a provider is rebuilt, a new Ref is now created. This avoids issues where an old build of a provider is still performing work.
• Updated AsyncValue documentations to use pattern matching.
• Added support for Ref/ProviderContainer.invalidate(provider, asReload: true)
• Failing providers are now automatically retried after a delay. The delay can be optionally configured.
• Fixed a bug when overriding a specific provider of a family, combined with dependencies: [family]

• Added AsyncNotifier.listenSelf. It was mistakenly absent from the 2.6.0 release

• Deprecated all Ref subclasses. Instead, use Ref itself.
• Deprecated Ref's type argument. Use Ref without its generic parameter instead.
• Deprecated any Ref member that used Ref's generic (such as Ref.state or Ref.listenSelf). Instead, use a Notifier.
• Added Notifier.listenSelf, as a replacement to Ref.listenSelf.
• Ref.watch and other methods now accept auto-dispose providers too.

• Fixed a typo in the documentation (thanks to @ljbkusters)

• Fixed various typos in the documentation (thanks to @kevalvavaliya)

• Deprecate ProviderScope.parent due to fundamentally not working. See https://github.com/rrousselGit/riverpod/issues/3261
• Improved Provider(dependencies: [...]) documentation.
• Fix out of date pub.dev description
• ref.invalidate now correctly clear all resources associated with the provider if the provider is no-longer used.
• Fix selectAsync sometimes never resolving.
• Fix ProviderSubscription.read returned by ref.listen(provider.future) not throwing if used after the subscription has been closed.
• Fix ref.onAddListener and other life-cycles not being triggered when listening to provider.future/provider.notifier.
• Fix a bug that caused Assertion failed: _lastFuture == null

• Fix out of date pub.dev description
• Add test argument to AsyncValue.guard method. (thanks to @utamori)

• Fix "pending timer" issue inside tests when using ref.keepAlive().
• Fix Ref.invalidate/Ref.refresh not throwing on circular dependency.
• Fix an infinite loop caused by ref.keepAlive if the KeepAliveLink is immediately closed.
• Fix container.exists(provider) on nested containers not checking their parent containers.

Fix exceptions when using multiple root ProviderContainers/ProviderScopes.

• Fix ProviderObserver.didUpdateProvider being called with an incorrect "provider" parameter when the provider is overridden.

• Exceptions in asynchronous providers are now correctly received by ProviderObserver.providerDidFail.
• Fix exception when a ProviderScope is rebuilt with a different key.

• Support assigning AsyncValue<T> to AsyncNotifier<void>.state

• riverpod upgraded to 2.4.4

• Fixed incorrect @visibleForTesting warning.

• Improved the error message when WidgetRef is used after the associated widget got unmounted.

• riverpod upgraded to 2.4.1

• riverpod upgraded to 2.4.0

• riverpod upgraded to 2.3.10

• Fix some exceptions causing Flutter asking to demangle stacktraces (#1874)
• Fix out of date AsyncValue docs.

• Added support for state_notifier 1.0.0
• Notifier.state is now accessible inside tests

• Improved error message for missing dependencies (thanks to @ValentinVignal)
• Fixed various typos in the documentation (thanks to @ValentinVignal)
• Fix not disposing autoDispose family providers
• Removed incorrect statement in ChangeNotifierProvider docs

• fix AsyncValue.isReloading docs

• Fixes an issue with nested ProviderScope (thanks to @jeiea)

• The debugger no-longer pauses on uncaught exceptions inside providers. This was voluntary, but too many people have complained that it often is a false positive.
• Removed unused dependency (thanks to @passsy)

• Deprecated the generic parameter of Family. This will enable implementing generic providers in riverpod_generator once it is removed.
• Updated documentation

• riverpod upgraded to 2.3.1

• Added StreamNotifier + StreamNotifierProvider. This is for building a StreamProvider while exposing ways to modify the stream.

  It is primarily meant to be used using code-generation via riverpod_generator, by writing:

  @riverpod
  class Example extends _$Example {
    @override
    Stream<Model> build() {
      // TODO return some stream
    }
  }
  

• Deprecated StreamProvider.stream Instead of:

  ref.watch(provider.stream).listen(...)
  

  do:

  ref.listen(provider, (_, value) {...});
  

  Instead of:

  final a = StreamProvider((ref) {
    return ref.watch(b.stream).map((e) => Model(e));
  })
  

  Do:

  final a = FutureProvider((ref) async {
    final e = await ref.watch(b.future);
    return Model(e);
  })
  

• Some restrictions on the dependencies parameter of providers have been lifted. It is no-longer necessary to include providers which do not themselves specify dependencies. All providers should specify dependencies if they are scoped at any point.

• Annotated Notifier.state setter as protected.

• Improve type-inference when using AsyncValue.whenOrNull (thanks to @AhmedLSayed9)
• Fixed AsyncValue.asError incorrectly not preserving the generic type
• Internal refactoring for riverpod_generator

Fixes an issue with FutureProvider<void> (#2028)

• It is now correctly possible to use ProviderSubscriptions inside ConsumerState.dispose (thanks to @1980)
• Update dependencies.
• fixes an exception on newer Dart versions
• fixes an edge-case where FutureProvider/AsyncNotifier did not emit the new state when the created Future completed (#1997)
• fixes errors inside FutureProvider/AsyncNotifier/StreamProvider not preserving the previous state (if any).
• Update dependencies.

Fix typos

A small release adding missing utilities and fixing some web related issues.

• Added provider.overrideWith((ref) => state)

• Added FutureProviderRef.future.

• Deprecated StateProvider.state Instead, use either ref.watch(stateProvider) or ref.read(stateProvider.notifier).state =

• Deprecated provider.overrideWithProvider. Instead use provider.overrideWith

• Added Ref.notifyListeners() to forcibly notify dependents. This can be useful for mutable state.

• Added @useResult to Ref.refresh/WidgetRef.refresh

• Added Ref.exists to check whether a provider is initialized or not.

• FutureProvider, StreamProvider and AsyncNotifierProvider now preserve the previous data/error when going back to loading. This is done by allowing AsyncLoading to optionally contain a value/error.

• Added AsyncValue.when(skipLoadingOnReload: bool, skipLoadingOnRefresh: bool, skipError: bool) flags to give fine control over whether the UI should show loading or data/error cases.

• Add AsyncValue.requireValue, to forcibly obtain the value and throw if in loading/error state

• Doing ref.watch(futureProvider.future) can no-longer return a SynchronousFuture. That behavior could break various Future utilities, such as Future.wait

• Add AsyncValue.copyWithPrevious(..., isRefresh: false) to differentiate rebuilds from ref.watch vs rebuilds from ref.refresh.

• ProviderContainer no-longer throws when disposed if it has an undisposed child ProviderContainer.

• Improved the error message when trying to modify a provider inside a widget life-cycle.

• Fixes a stackoverflow on Web caused by Dart (thanks to @leehack)

• Fixes a bug when the root ProviderContainer is not associated with a ProviderScope.

• Fixes a case where a circular dependency between providers was incorrectly allowed (#1766)

• FIX: Fixed an assert error if a family depends on itself while specifying dependencies. (#1721).

2.0.2 #

Fixed an assert error if a family depends on itself while specifying dependencies.

Updated changelog (see 2.0.0)

Here is the changelog for all the changes in the 2.0 version. An article is in progress and will be linked here once available.

Breaking changes:

• FutureProvider.stream is removed.
• Using overrideWithProvider, it is no-longer possible to override a provider with a different type of provider (such as overriding FutureProvider with a StreamProvider).
• AsyncError.stackTrace is now a required positional parameter and non-nullable
• All overrideWithValue methods are removed, besides Provider.overrideWithValue. This change is temporary, and these methods will be reintroduced in a later version. In the meantime, you can use overrideWithProvider.
• Modifiers (provider.future, provider.state, ...) no-longer are providers, and therefore no-longer appear inside ProviderObserver.
• The Reader typedef is removed. Use Ref instead.
• ProviderListener is removed. Used ref.listen instead.
• Removed the deprecated ProviderReference.
• Providers no-longer throw a ProviderException if an exception was thrown while building their value. Instead, they will rethrow the thrown exception and its stacktrace.
• It is no longer possible to pass provider.future/.notifier/... to the parameter dependencies of provider. Passing the provider directly is enough.
• The Family type now has a single generic parameter instead of 3.

Non-breaking changes:

• Upgrade minimum required Flutter SDK version to 3.0.0
• Upgrade minimum required Dart SDK version to 2.17.0
• Added WidgetRef.context. This allows functions that depend on a WidgetRef to use the BuildContext without having to receive it as parameter.
• Added provider.selectAsync, which allows to both await an async value while also filtering rebuilds.
• Added WidgetRef.listenManual for listening to providers in a widget outside of build.
• Added ref.listenSelf, for subscribing to changes of a provider within that provider. That can be useful for logging purposes or storing the state of a provider in a DB.
• Added container.invalidate(provider)/ref.invalidate(provider) and ref.invalidateSelf(). These are similar to ref.refresh methods, but do not immediately rebuild the provider.

These methods are safer than ref.refresh as they can avoid a provider rebuilding twice in a quick succession.

• Added ref.onAddListener, ref.onRemoveListener, ref.onCancel and ref.onResume. All of which allow performing side-effects when providers are listened or stop being listened.

• A new AutoDisposeRef.keepAlive() function is added. It is meant to replace AutoDisposeRef.maintainState to make logic for preventing the disposal of a provider more reusable.

• feat; AutoDisposeRef.maintainState is deprecated. Use the new AutoDisposeRef.keepAlive() instead.

• Add support for ref.invalidate(family) to recompute an entire family (#1517)

• Added AsyncValue.valueOrNull to obtain the value while ignoring potential errors.

• Added new functionalities to AsyncValue: hasError, hasData, asError, isLoading , copyWithPrevious and unwrapPrevious.

Fixes:

• fixed a bug where AsyncValue.whenData did not preserve AsyncValue.isLoading/isRefreshing
• StateProvider and StateNotifierProvider no longer notify their listeners on ref.refresh if the new result is identical to the old one.
• fixed potential null exception when using autoDispose
• fixed a bug where unmounting a nested ProviderScope could cause an exception (#1400)
• Fixed an issue where providers were incorrectly allowed to depend on themselves, breaking autoDispose in the process.
• Fixed a memory leak when using StateProvider.autoDispose's .state
• Fix ProviderObserver.didDisposeProvider not executing on provider refresh.
• Fixed an issue where AsyncValue.value did not throw if there is an error.
• Fixed a cast error when overriding a provider with a more specific provider type (#1100)
• Fixed a bug where onDispose listeners could be executed twice under certain conditions when using autoDispose.
• Fixed an issue where refreshing a provider.future/provider.stream did work properly
• Fixed false positive with ref.watch asserts

Removed an assert preventing from overriding the same provider/family multiple times on a ProviderScope/ProviderContainer.

Fixed a null exception on web

Improved the performance of the assert which verifies that providers properly respect their dependencies variable.

Riverpod is now stable!

General changes #

• Breaking: ProviderContainer.debugProviderValues and ProviderContainer.debugProviderElements are removed. You can now instead use ProviderContainer.getAllProviderElements.

• ChangeNotifierProvider now supports nullable ChangeNotifier (#856)

• Increased minimum SDK version to 2.14.0

• Breaking The return value when reading a StateProvider changed. Before, doing ref.read(someStateProvider) would return the StateController instance. Now, this will only return the state of the StateController. This new behavior matches StateNotifierProvider.

  For a simple migration, the old behavior is available by writing ref.read(someStateProvider.state).

• Added ref.listen for triggering actions inside providers/widgets when a provider changes.

  It can be used to listen to another provider without recreating the provider state:

  final counterProvider = StateNotifierProvider<Counter, int>(...);
  
  final anotherProvider = Provider<T>((ref) {
    ref.listen<int>(counterProvider, (previous, count) {
      print('counter changed from $previous to $count');
    });
  });
  

  Alternatively, it can be used by widgets to show modals/dialogs:

  final counterProvider = StateNotifierProvider<Counter, int>(...);
  
  class Example extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      ref.listen<int>(counterProvider, (previous, count) {
        showDialog(...);
      });
    }
  }
  

• ProviderListener is deprecated in favor of ref.listen.

• It is now possible to "await" all providers that emit an AsyncValue (previously limited to FutureProvider/StreamProvider). This includes cases where a StateNotifierProvider exposes an AsyncValue:

  class MyAsyncStateNotifier extends StateNotifier<AsyncValue<MyState>> {
    MyAsyncStateNotifier(): super(AsyncValue.loading()) {
      // TODO fetch some data and update the state when it is obtained
    }
  }
  
  final myAsyncStateNotifierProvider = StateNotifierProvider<MyAsyncStateNotifier, AsyncValue<MyState>>((ref) {
    return MyAsyncStateNotifier();
  });
  
  final someFutureProvider = FutureProvider((ref) async {
    MyState myState = await ref.watch(myAsyncStateNotifierProvider.future);
  });
  

• Deprecated StreamProvider.last in favor of StreamProvider.future.

• StreamProvider.future, StreamProvider.stream and FutureProvider.future now expose a future/stream that is independent from how many times the associated provider "rebuilt":

  • if a StreamProvider rebuild before its stream emitted any value, StreamProvider.future will resolve with the first value of the new stream instead.
  • if a FutureProvider rebuild before its future completes, FutureProvider.future will resolve with the result of the new future instead.

• You can now override any provider with any other provider, as long as the value that they expose matches. For example, it is possible to override a StreamProvider<Model> with a Provider<AsyncValue<Model>>.

• ref.onDispose now calls the dispose function as soon as one of the provider's dependency is known to have changed

• Providers can now call ref.refresh to refresh a provider, instead of having to do ref.container.refresh.

• Providers no longer wait until their next read to recompute their state if one of their dependency changed and they have listeners.

• Added ProviderContainer.pump, a utility to easily "await" until providers notify their listeners or are disposed.

• fixed an issue when using both family and autoDispose that could lead to an inconsistent state

Unified the syntax for interacting with providers #

• Breaking: The prototype of ConsumerWidget's build and Consumer's builder changed. Before:

  class Example extends ConsumerWidget {
    @override
    Widget build(BuildContext context, ScopedReader watch) {
      int count = watch(counterProvider);
      ...
    }
  }
  

  After:

  class Example extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      int count = ref.watch(counterProvider);
      ...
    }
  }
  

• ProviderListener is deprecated. Instead, use ref.listen:

  class Example extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      ref.listen<int>(counter, (count) {
        print('count changed $count');
      });
    }
  }
  

• Added ConsumerStatefulWidget + ConsumerState, a variant of StatefulWidgets that have access to a WidgetRef.

• All "watch" functions now support myProvider.select((value) => ...). This allows filtering rebuilds:

  final userProvider = StateNotifierProvider<UserController, User>(...);
  
  Consumer(
    builder: (context, ref, _) {
      // With this syntax, the Consumer will not rebuild if `userProvider`
      // emits a new User but its "name" didn't change.
      bool userName = ref.watch(userProvider.select((user) => user.name));
    },
  )
  

• ProviderReference is deprecated in favor of Ref.

• Breaking: ProviderObserver.didUpdateProvider now receives both the previous and new value.

• Breaking: ProviderObserver.mayHaveChanged is removed.

• Breaking: Family.overrideWithProvider now must create a provider:

  final family = Provider.family<State, Arg>(...);
  
  family.overrideWithProvider(
    (Arg arg) => Provider<State>((ref) => ...)
  );
  

• All providers now receive a custom subclass of ProviderRefBase as a parameter:

  Provider<T>((ProviderRef<T> ref) {...});
  FutureProvider<T>((FutureProviderRef<T> ref) {...});
  StateProvider<T>((StateProviderRef<T> ref) {...});
  

  That allows providers to implement features that is not shared with other providers.

  • Provider, FutureProvider and StreamProvider's ref now have a state property, which represents the currently exposed value. Modifying it will notify the listeners:

    Provider<int>((ref) {
      ref.listen(onIncrementProvider, (_) {
        ref.state++;
      });
    
      return 0;
    });
    

  • StateProvider's ref now has a controller property, which allows the provider to access the StateController exposed.

• Breaking: ProviderReference.mounted is removed. You can implement something similar using onDispose:

  Provider<T>((ref) {
    var mounted = true;
    ref.onDispose(() => mounted = false);
  });
  

All providers can now be scoped. #

• Breaking: ScopedProvider is removed. To migrate, change ScopedProviders to Providers.

• All providers now come with an extra named parameter called dependencies. This parameter optionally allows defining the list of providers/families that this new provider depends on:

  final a = Provider(...);
  
  final b = Provider((ref) => ref.watch(a), dependencies: [a]);
  

  By doing so, this will tell Riverpod to automatically override b if a gets overridden.

Updated AsyncValue: #

• Breaking AsyncValue.copyWith is removed

• Breaking AsyncValue.error(..., stacktrace) is now a named parameter instead of positional parameter.

• Deprecated AsyncValue.data in favor of AsyncValue.value

• Allowed AsyncData, AsyncError and AsyncLoading to be extended

• Added AsyncValue.whenOrNull, similar to whenOrElse but instead of an "orElse" parameter, returns null.

• Added AsyncValue.value, which allows reading the value without handling loading/error states.

• AsyncError can now be instantiated with const.

• Added StateController.update, to simplify updating the state from the previous state:

  final provider = StateController((ref) => 0);
  ...
  ref.read(provider).update((state) => state + 1);
  

• It is no longer allowed to use ref.watch or ref.read inside a selector:

  provider.select((value) => ref.watch(something)); // KO, cannot user ref.watch inside selectors
  

• FutureProvider now creates a FutureOr<T> instead of a Future<T>. That allows bypassing the loading state in the event where a value was synchronously available.

Bug fixes #

• Fixed a bug where widgets were not rebuilding in release mode under certain conditions
• FIX: StreamProvider.last no longer throws a StateError when no value were emitted (#296).
• fixed an issue where when chaining providers, widgets may re-render a frame late, potentially causing a flicker. (see #648)

Fixed an issue where dependencies did not work for ChangeNotifierProvider (#800)

Fixed a bug where reading a provider within a consumer could throw (#796)

Fix an issue where *Provider.autoDispose were not able to specify the dependencies parameter.

Future/StreamProvider #

• FutureProvider now creates a FutureOr<T> instead of a Future<T> That allows bypassing the loading state in the event where a value was synchronously available.

• During loading and error states, FutureProvider and StreamProvider now expose the latest value through AsyncValue. That allows UI to show the previous data while some new data is loading, instead of showing a spinner:

  final provider = FutureProvider<User>((ref) async {
    ref.watch(anotherProvider); // may cause `provider` to rebuild
  
    return fetchSomething();
  })
  ...
  
  Widget build(context, ref) {
    return ref.watch(provider).when(
      error: (err, stack, _) => Text('error'),
      data: (user) => Text('Hello ${user.name}'),
      loading: (previous) {
        if (previous is AsyncData<User>) {
          return Text('loading ... (previous: ${previous.value.name})');
        }
  
        return CircularProgressIndicator();
      }
    );
  
  }
  

AsyncValue #

• Breaking AsyncValue.copyWith is removed
• Breaking AsyncValue.error(..., stacktrace) is now a named parameter instead of positional parameter.
• Breaking AsyncValue.when(loading: ) and AsyncValue.when(error: ) (and when variants) now receive an extra "previous" parameter.
• Deprecated AsyncValue.data in favor of AsyncValue.value
• Allowed AsyncData, AsyncError and AsyncLoading to be extended
• Added AsyncValue.whenOrNull, similar to whenOrElse but instead of an "orElse" parameter, returns null.
• Added AsyncValue.value, which allows reading the value without handling loading/error states.
• AsyncError can now be instantiated with const.
• AsyncLoading and AsyncError now optionally includes the previous state.

General #

• Breaking All overrideWithProvider methods are removed. To migrate, instead use overrideWithValue.

• All providers now come with an extra named parameter called dependencies. This parameter optionally allows defining the list of providers/families that this new provider depends on:

  final a = Provider(...);
  
  final b = Provider((ref) => ref.watch(a), dependencies: [a]);
  

  By doing so, this will tell Riverpod to automatically override b if a gets overridden.

• Added StateController.update, to simplify updating the state from the previous state:

  final provider = StateController((ref) => 0);
  ...
  ref.read(provider).update((state) => state + 1);
  

• It is no longer allowed to use ref.watch or ref.read inside a selector:

  provider.select((value) => ref.watch(something)); // KO, cannot user ref.watch inside selectors
  

Bug-fixes #

• fixed a bug where providers were rebuilding even when not listened to
• fixed ref.listen now working when downcasing the value of a provider.
• fixed a bug where disposing a scoped ProviderContainer could cause other ProviderContainers to stop working.
• fixed an issue where conditionally depending on an "autoDispose" provider may not properly dispose of it (see #712)
• fixed an issue where when chaining providers, widgets may re-render a frame late, potentially causing a flicker. (see #648)

• Fixed ProviderObserver not working when modifying a StateProvider.
• Fixed a bug where scoped provider were potentially not disposed
• Fixed a bug where widgets were not rebuilding in release mode under certain conditions

• FIX: StreamProvider.last no longer throws a StateError when no value were emitted (#296).
• Re-enabled debug assertions that were temporarily disabled by previous dev versions.
• Allows families to be scoped/overridden
• Fixed bugs with ref.refresh not working on some providers
• renamed ProviderBase.recreateShouldNotify to updateShouldNotify

Fixed an issue where provider listeners could not be called properly.

Fixed various issues related to scoped providers.

• All providers can now be scoped.
• breaking: ScopedProvider is removed. To migrate, change ScopedProviders to Providers.

• Add missing exports (see #532)

• Breaking: The prototype of ConsumerWidget's build and Consumer's builder changed. Before:

  class Example extends ConsumerWidget {
    @override
    Widget build(BuildContext context, ScopedReader watch) {
      int count = watch(counterProvider);
      ...
    }
  }
  

  After:

  class Example extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      int count = ref.watch(counterProvider);
      ...
    }
  }
  

• ProviderListener is deprecated. Instead, use ref.listen:

  class Example extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      ref.listen<int>(counter, (count) {
        print('count changed $count');
      });
    }
  }
  

• Added ConsumerStatefulWidget + ConsumerState, a variant of StatefulWidgets that have access to a WidgetRef.

• All "watch" functions now support myProvider.select((value) => ...). This allows filtering rebuilds:

  final userProvider = StateNotifierProvider<UserController, User>(...);
  
  Consumer(
    builder: (context, ref, _) {
      // With this syntax, the Consumer will not rebuild if `userProvider`
      // emits a new User but its "name" didn't change.
      bool userName = ref.watch(userProvider.select((user) => user.name));
    },
  )
  

• Breaking: Family.overrideWithProvider now must create a provider:

  final family = Provider.family<State, Arg>(...);
  
  family.overrideWithProvider(
    (Arg arg) => Provider<State>((ref) => ...)
  );
  

• Breaking: ProviderObserver.didUpdateProvider now receives both the previous and new value.

• Breaking: ProviderObserver.mayHaveChanged is removed.

• Added ref.listen, used to listen to another provider without recreating the provider state:

  final counter = StateNotifierProvider<Counter, int>(...);
  
  final anotherProvider = Provider<T>((ref) {
    ref.listen<int>(counter, (count) {
      print('counter change: $count');
    });
  });
  

• ProviderReference is deprecated in favor of ProviderRefBase.

• All providers now receive a custom subclass of ProviderRefBase as a parameter:

  Provider<T>((ProviderRef<T> ref) {...});
  FutureProvider<T>((FutureProviderRef<T> ref) {...});
  StateProvider<T>((StateProviderRef<T> ref) {...});
  

  That allows providers to implement features that is not shared with other providers.

  • Provider, FutureProvider and StreamProvider's ref now have a state property, which represents the currently exposed value. Modifying it will notify the listeners:

    Provider<int>((ref) {
      ref.listen(onIncrementProvider, (_) {
        ref.state++;
      });
    
      return 0;
    });
    

  • StateProvider's ref now has a controller property, which allows the provider to access the StateController exposed.

• Breaking: ProviderReference.mounted is removed. You can implement something similar using onDispose:

  Provider<T>((ref) {
    var mounted = true;
    ref.onDispose(() => mounted = false);
  });
  

• Breaking: ProviderContainer.debugProviderValues and ProviderContainer.debugProviderElements are removed. You can now instead use ProviderContainer.getAllProviderElements.

• StreamProvider.last, StreamProvider.stream and FutureProvider.future now expose a future/stream that is independent from how many times the associated provider "rebuilt":

  • if a StreamProvider rebuild before its stream emitted any value, StreamProvider.last will resolve with the first value of the new stream instead.
  • if a FutureProvider rebuild before its future completes, FutureProvider.future will resolve with the result of the new future instead.

• You can now override any provider with any other provider, as long as the value that they expose matches. For example, it is possible to override a StreamProvider<Model> with a Provider<AsyncValue<Model>>.

• Providers can now call ref.refresh to refresh a provider, instead of having to do ref.container.refresh.

• ref.onDispose now calls the dispose function as soon as one of the provider's dependency is known to have changed

• Providers no longer wait until their next read to recompute their state if one of their dependency changed and they have listeners.

• Added ProviderContainer.pump, a utility to easily "await" until providers notify their listeners or are disposed.

• fixed an issue when using both family and autoDispose that could lead to an inconsistent state

Removed an assert that could cause issues when an application is partially migrated to null safety.

• Fix context.refresh not compiling when using nullable providers

• Re-added StateProvider.overrideWithValue/StateProvider.overrideWithProvider that were involuntarily removed.

• BREAKING CHANGE The Listener/LocatorMixin typedefs are removed as the former could cause a name conflict with the widget named Listener and the latter is not supported when using Riverpod.

• BREAKING CHANGE The syntax for using StateNotifierProvider was updated. Before:

  class MyStateNotifier extends StateNotifier<MyModel> {...}
  
  final provider = StateNotifierProvider<MyStateNotifier>((ref) => MyStateNotifier());
  
  ...
  Widget build(context, watch) {
    MyStateNotifier notifier = watch(provider);
    MyModel model = watch(provider.state);
  }
  

  After:

  class MyStateNotifier extends StateNotifier<MyModel> {...}
  
  final provider = StateNotifierProvider<MyStateNotifier, MyModel>>((ref) => MyStateNotifier());
  
  ...
  Widget build(context, watch) {
    MyStateNotifier notifier = watch(provider.notifier);
    MyModel model = watch(provider);
  }
  

  See also https://github.com/rrousselGit/riverpod/issues/341 for more information.

• BREAKING CHANGE It is no longer possible to override StreamProvider.stream/last and FutureProvider.future.

• feat: Calling ProviderContainer.dispose multiple time no longer throws. This simplifies the tear-off logic of tests.

• feat: Added ChangeNotifierProvider.notifier and StateProvider.notifier They allow obtaining the notifier associated with the provider, without causing widgets/providers to rebuild when the state updates.

• fix: overriding a StateNotifierProvider/ChangeNotifierProvider with overrideWithValue now correctly listens to the notifier.

Fixed an issue where context.read and ProviderListener were unable to read providers that return a nullable value

• Fixed a bug where overriding a FutureProvider with an error value could cause tests to fail (see https://github.com/rrousselGit/riverpod/issues/355)

• stable null-safety release
• ProviderObserver can now have a const constructor
• Added the mechanism for state-inspection using the Flutter devtool
• loosened the version constraints of freezed_annotation
• deprecated import 'flutter_riverpod/all.dart'. Now everything is available with flutter_riverpod/flutter_riverpod.dart.
• Fixed a but where listening to StreamProvider.last could result in a StateError (#217)
• removed the assert preventing ConsumerWidget's "watch" from being used after the build method completed. This allows "watch" to be used inside ListView.builder.
• context.read(myProvider) now accepts ScopeProviders

• deprecated import 'flutter_riverpod/all.dart'. Now everything is available with flutter_riverpod/flutter_riverpod.dart.
• removed the assert preventing ConsumerWidget's "watch" from being used after the build method completed. This allows "watch" to be used inside ListView.builder.
• context.read(myProvider) now accepts ScopeProviders

• Fixed outdated doc

• Fixed a but where listening to StreamProvider.last could result in a StateError (#217)

Migrated to null-safety

• Exported AutoDisposeProviderRefBase

• Fixed an remaining memory leak related to StreamProvider (see also https://github.com/rrousselGit/riverpod/issues/193)

• Breaking FutureProvider and StreamProvider no longer supports null as a valid value.
• Fixed a memory leak with StreamProvider (see also https://github.com/rrousselGit/riverpod/issues/193)
• Fixed an error message typo related to Consumer

• Fixed a bug where providers (usually ScopedProviders) did not dispose correctly (see also https://github.com/rrousselGit/riverpod/issues/154).

• Fixed a bug where hot-reload did not work for ConsumerWidget/Consumer

• package:flutter_riverpod/flutter_riverpod.dart now exports StateNotifier
• Marked the providers with @sealed so that the IDE warns against implementing/subclassing providers.
• Fix mistakes in AsyncValue.guard's documentation (thanks @mono0926)
• Loosened the version constraints of freezed_annotation to support 0.12.0

• Fixed invalid version error

• Fixed a bug where the state of a provider may be disposed when it shouldn't be disposed.

• Added a way to import the implementation class of providers with modifiers, such as AutoDisposeProvider.

  This is useful if you want to use Riverpod with the lint always_specify_types:

  import 'package:flutter_riverpod/all.dart';
  
  final AutoDisposeStateProvider<int> counter = StateProvider.autoDispose<int>((ProviderRefBase ref) {
    return 0;
  });
  

  If you do not use this lint, prefer using the default import instead, to not pollute your auto-complete.

• Breaking Updating ProviderListener so that onChange receives the BuildContext as a parameter (thanks to @tbm98)

• Renamed ProviderContainer.debugProviderStates to ProviderContainer.debugProviderElements
• Fixed a bug where updating ProviderScope.overrides may cause an exception for no reason (see https://github.com/rrousselGit/riverpod/issues/107)

Fixed a bug that prevented the use of ConsumerWidget under normal circumstances

• Fixed a bug where in release mode, ScopedProvider did not update correctly (https://github.com/rrousselGit/riverpod/issues/101)

• Breaking: Consumer is slightly modified to match other Builders like ValueListenableBuilder. Before:

  return Consumer((context, watch) {
    final value = watch(myProvider);
    return Text('$value');
  });
  

  after:

  return Consumer(
    builder: (context, watch, child) {
      final value = watch(myProvider);
      return Text('$value');
    },
  );
  

• Added a ConsumerWidget class which can be extended to make a StatelessWidget that can read providers:

  class MyWidget extends ConsumerWidget {
    const MyWidget({Key? key}) : super(key: key);
  
    @override
    Widget build(BuildContext context, ScopedReader watch) {
      final value = watch(myProvider);
      return Text('$value');
    }
  }
  

• ref.watch on non ".autoDispose" providers can no longer read ".autoDispose" providers.

  For more info, see http://riverpod.dev/docs/concepts/modifiers/auto_dispose#the-argument-type-autodisposeprovider-cant-be-assigned-to-the-parameter-type-alwaysaliveproviderbase

• ScopedProvider now accepts null as a function:

  final example = ScopedProvider<int>(null);
  

  Which is equivalent to:

  final example = ScopedProvider<int>((watch) => throw UnimplementedError(''));
  

• Fixed a bug where context.refresh may not work properly if the widget tree contains multiple ProviderScope.

• Fixed a bug where when disposing ProviderContainer, providers may be disposed in an incorrect order.
• Improved the performances of reading providers by 25%

• Merged Computed and Provider. Now, all providers have the ability to rebuild their state when one of the object they listen changed.

  To migrate, change:

  final provider = Provider(...);
  final example = Computed((watch) {
    final value = watch(provider);
    return value;
  });
  

  into:

  final provider = Provider(...);
  final example = Provider((ref) {
    final value = ref.watch(provider);
    return value;
  });
  

• Computed (now Provider) no longer deeply compare collections to avoid rebuilds. Comparing the content of lists is quite expensive and actually rarely useful. Now, a simple == comparison is used.

• Renamed ProviderStateOwner to ProviderContainer

• Renamed ProviderStateOwnerObserver to ProviderObserver

• It is no longer possible to override a provider anywhere in the widget tree. Providers can only be overridden in the top-most ProviderScope/ProviderContainer.

• Providers can now read values which may change over time using ref.read and ref.watch. When using ref.watch, if the value obtained changes, this will cause the provider to re-create its state.

• It is no longer possible to add ProviderObserver anywhere in the widget tree. They can be added only on the top-most ProviderScope/ProviderContainer.

• Provider.read(BuildContext) is changed into context.read(provider), and can now read Provider.autoDispose.

• Added ProviderContainer.refresh(provider) and context.refresh(provider). These method allows forcing the refresh of a provider, which can be useful for things like "retry on error" or "pull to refresh".

• ref.read(StreamProvider<T>) no longer returns a Stream<T> but an AsyncValue<T> Before:

  final streamProvider = StreamProvider<T>(...);
  final example = Provider((ref) {
    Stream<T> stream = ref.read(streamProvider);
  });
  

  After:

  final streamProvider = StreamProvider<T>(...);
  final example = Provider((ref) {
    Stream<T> stream = ref.watch(streamProvider.steam);
  });
  

• ref.read(FutureProvider<T>) no longer returns a Future<T> but an AsyncValue<T>

  Before:

  final futureProvider = FutureProvider<T>(...);
  final example = Provider((ref) {
    Future<T> future = ref.read(futureProvider);
  });
  

  After:

  final futureProvider = FutureProvider<T>(...);
  final example = Provider((ref) {
    Future<T> future = ref.watch(futureProvider.future);
  });
  

• Removed ref.dependOn. You can now use ref.read/ref.watch to achieve the same effect.

  Before:

  final streamProvider = StreamProvider<T>(...);
  final example = Provider((ref) {
    Future<T> last = ref.dependOn(streamProvider).last;
  });
  

  After:

  final streamProvider = StreamProvider<T>(...);
  final example = Provider((ref) {
    Future<T> last = ref.watch(streamProvider.last);
  });
  

• Provider.readOwner(ProviderStateOwner) is changed into ProviderContainer.read(Provider)

• Provider.watchOwner(ProviderStateOwner, (value) {}) is changed into:

  ProviderContainer container;
  final provider = Provider((ref) => 0);
  
  final subscription = container.listen(
    provider,
    mayHaveChanged: (sub) {},
    didChange: (sub) {}.
  );
  
  subscription.close();
  

• MyProvider.family.autoDispose now correctly free both the arguments and the associated providers from memory when the provider is no longer listened to.

• Added ScopedProvider, a new kind of provider that can be overridden anywhere in the widget tree. Normal providers cannot read a ScopedProvider.

• Added ProviderListener, a widget which allows listening to a provider without rebuilding the widget-tree. This can be useful for showing modals and pushing routes.

• Fixed the documentation of StateNotifierProvider incorrectly showing the documentation of StreamProvider.
• Improve the documentation of StateProvider.

• Changed ComputedFamily into Computed.family
• Added [AsyncValue.guard](https://pub.dev/documentation/riverpod/latest/riverpod/AsyncValue/guard.html to simplify transforming a Future into an AsyncValue.
• Improved the documentation of the different providers

Changed the syntax of "AutoDispose*" and "*Family" to use a syntax similar to named constructors instead.

Before:

final myProvider = AutoDisposeStateNotifierProviderFamily<MyStateNotifier, int>((ref, id) {
  return MyStateNotifier(id: id);
});

After:

final myProvider = StateNotifierProvider.autoDispose.family<MyStateNotifier, int>((ref, id) {
  return MyStateNotifier(id: id);
});

The behavior is the same. Only the syntax changed.

• Added AsyncValue.whenData, syntax sugar for AsyncValue.when to handle only the data case and do nothing for the error/loading cases.

• Fixed a bug that caused [Computed] to crash if it stopped being listened to then was listened to again.

• Computed and Consumer now correctly unsubscribe to a provider when their function stops using a provider.

• ref.read is renamed as ref.dependOn
• Deprecated ref.dependOn(streamProvider).stream and ref.dependOn(futureProvider).future in favor of a universal ref.dependOn(provider).value.
• added ref.read(provider), syntax sugar for ref.dependOn(provider).value.

Initial release