Fix typos and broken links in the documentation
debugPrintRebuildDirtyWidgetsAdded error details for provider that threw during the creation (thanks to @jmewes)
Removed the assert that prevented from using ChangeNotifierProvider with notifiers that already had listeners.
Breaking: It is no longer possible to define providers where their only difference is the nullability of the exposed value:
MultiProvider( providers: [ Provider<Model>(...), Provider<Model?>(...) ] )
Before, when defining those providers, doing context.watch<Model> vs context.watch<Model?> would point to a different provider. Now, both will always point to the deepest provider (in this example Provider<Model?>).
That fixes issues where a common developer mistake is to define a provider as Model? but try to read it as Model. Previously, that would give a ProviderNotFoundException. Now, this will correctly resolve the value.
That also helps large codebase migrate to null-safety progressively, as they would temporarily contain both null-safe and unsound code. Previously, unsound code would be unable to read a provider defined as Provider<Model?>, as Model? is not a valid syntax. With this change, this is now feasible.
It is now possible to read a provider without throwing a ProviderNotFoundException if the provider is optional.
To do so, when calling context.watch/context.read, make the generic type nullable. Such that instead of:
context.watch<Model>()
which will throw a ProviderNotFoundException if no matching providers are found, do:
context.watch<Model?>()
which will try to obtain a matching provider. But if none are found, null will be returned instead of throwing.
Breaking: It is no longer possible to define providers where their only difference is the nullability of the exposed value:
MultiProvider( providers: [ Provider<Model>(...), Provider<Model?>(...) ] )
Before, when defining those providers, doing context.watch<Model> vs context.watch<Model?> would point to a different provider. Now, both will always point to the deepest provider (in this example Provider<Model?>).
That fixes issues where a common developer mistake is to define a provider as Model? but try to read it as Model. Previously, that would give a ProviderNotFoundException. Now, this will correctly resolve the value.
That also helps large codebase migrate to null-safety progressively, as they would temporarily contain both null-safe and unsound code. Previously, unsound code would be unable to read a provider defined as Provider<Model?>, as Model? is not a valid syntax. With this change, this is now feasible.
It is now possible to read a provider without throwing a ProviderNotFoundException if the provider is optional.
To do so, when calling context.watch/context.read, make the generic type nullable. Such that instead of:
context.watch<Model>()
which will throw a ProviderNotFoundException if no matching providers are found, do:
context.watch<Model?>()
which will try to obtain a matching provider. But if none are found, null will be returned instead of throwing.
StreamProviderFixed an issue where providers with an update parameter in sound null-safety mode could throw null exceptions.
nested dependency to 1.0.0 and collection to 1.15.0ProviderNotFoundException to mention hot-reload. (#595)ChangeNotifiers in ChangeNotifierProvider() to have listeners (#596)context.watch/context.read that prevented them to be used inside specific conditions (#585)create of a provider`ValueListenableProvider.value (the default constructor is still removed).Migrated Provider to non-nullable types:
initialData for both FutureProvider and StreamProvider is now required.
To migrate, what used to be:
FutureProvider<int>( create: (context) => Future.value(42), child: MyApp(), ) Widget build(BuildContext context) { final value = context.watch<int>(); return Text('$value'); }
is now:
FutureProvider<int?>( initialValue: null, create: (context) => Future.value(42), child: MyApp(), ) Widget build(BuildContext context) { // be sure to specify the ? in watch<int?> final value = context.watch<int?>(); return Text('$value'); }
ValueListenableProvider is removed
To migrate, you can instead use Provider combined with ValueListenableBuilder:
ValueListenableBuilder<int>( valueListenable: myValueListenable, builder: (context, value, _) { return Provider<int>.value( value: value, child: MyApp(), ); } )
ProviderNotFoundException to mention hot-reload. (#595)ChangeNotifiers in ChangeNotifierProvider() to have listeners (#596)context.watch/context.read that prevented them to be used inside specific conditions (#585)ValueListenableProvider is no-longer deprecated. Only its default constructor is deprecated (the .value constructor is kept)
Marked ValueListenableProvider as deprecated
Improve pub score
Documentation improvement about the builder parameter of Providers.
Fixed typo in the error message of ProviderNotFoundException
ReassembleHandler interface, for objects to implement so that provider let them handle hot-reload.Added a builder parameter on MultiProvider (thanks to @joaomarcos96):
MultiProvider( providers: [ ChangeNotifierProvider(create: (ct) => Counter()), ], builder: (ctx, child) { final counter = ctx.watch<Counter>(); return Text('${counter.count}'); }, );
Improved the error message of ProviderNotFoundException with instructions that better fit what is usually the problem.
Added documentation on why context.read should not be called inside build, and what to do instead.
Improved the performances of context.select, by not calling the selectors when the provider changes if the widgets listening to the value are already needing build.
Fixes a bug where context.watch couldn't be called inside ListView/LayoutBuilder
Improve the error message when trying to use context.select inside ListView.builder
Improve the error message when calling context.read/watch/select/Provider.of with a context that is null.
beta channel.context.select, leading to memory leaks and unnecessary rebuildsbuilder parameter of providers not working (thanks to @passsy)Now requires:
Added a select extension on BuildContext. It behaves similarly to Selector, but is a lot less verbose to write:
With Selector:
Widget build(BuildContext context) { return Selector<Person, String>( selector: (_, p) => p.name, builder: (_, name, __) { return Text(name); }, ), }
VS with the new select extension:
Widget build(BuildContext context) { final name = context.select((Person p) => p.name); return Text(name); }
Added builder on the different providers. This parameter simplifies situations where we need a BuildContext that can access the new provider.
As such, instead of:
Provider( create: (_) => Something(), child: Builder( builder: (context) { final name = context.select((Something s) => s.name); return Text(name); }, ), )
we can write:
Provider( create: (_) => Something(), builder: (context, child) { final name = context.select((Something s) => s.name); return Text(name); }, )
The behavior is the same. This is only a small syntax sugar.
Added a two extensions on BuildContext, to slightly reduce the boilerplate:
| before | after |
|---|---|
Provider.of<T>(context, listen: false) | context.read<T>() |
Provider.of<T>(context) | context.watch<T> |
Added a Locator typedef and an extension on BuildContext, to help with being able to read providers from a class that doesn't depend on Flutter.
child when using a provider outside of MultiProvider (thanks to @felangel)Provider.of is called without specifying listen: false outside of the widget tree.Provider.of returning the previous value instead of the new value if called inside didChangeDependencies.update was unnecessarily called.removed the inference of the listen flag of Provider.of in favor of an exception in debug mode if listen is true when it shouldn't.
This is because it caused a critical performance issue. See https://github.com/rrousselGit/provider/issues/305
Selector now deeply compares collections by default, and offers a shouldRebuild to customize the rebuild behavior.ProviderNotFoundError to ProviderNotFoundException. This allows calling Provider.of inside a try/catch without triggering a warning.listen argument of Provider.of is now automatically inferred. It is no longer necessary to pass listen: false when calling Provider.of outside of the widget tree.initialBuilder & builder of *ProxyProvider to create & updatebuilder of *Provider to create*ProxyProvider0 variantAdded Selector, similar to Consumer but can filter unneeded updates
improved the overall documentation
fixed a bug where ChangeNotifierProvider.value didn't update dependents when the ChangeNotifier instance changed.
Consumer can now be used inside MultiProvider
MultiProvider( providers: [ Provider(builder: (_) => Foo()), Consumer<Foo>( builder: (context, foo, child) => Provider.value(value: foo.bar, child: child), ) ], );
Provider now throws if used with a Listenable/Stream. This can be disabled by setting Provider.debugCheckInvalidValueType to null.StreamProvider has now builds a Stream instead of StreamController. The previous behavior has been moved to StreamProvider.controller.XXProvider.value constructors now use value as parameter name.FutureProvider, which takes a future and updates dependents when the future completes.const constructors.ProxyProvider, ListenableProxyProvider, and ChangeNotifierProxyProvider. These providers allows building values that depends on other providers, without loosing reactivity or manually handling the state.DelegateWidget and a few related classes to help building custom providers.InheritedWidget to help building custom providers.ListenableProvider.value/ChangeNotifierProvider.value /StreamProvider.value/ValueListenableProvider.value subscribed/unsubscribed to their respective object too oftenListenableProvider.value/ChangeNotifierProvider.value may rebuild too often or skip some.Consumer now takes an optional child argument for optimization purposes.Provider and StatefulProviderValueListenableProvidervalue named constructor.Provider.of<T> now crashes with a ProviderNotFoundException when no Provider<T> are found in the ancestors of the context used.ChangeNotifierProvider, similar to scoped_model that exposes ChangeNotifer subclass and rebuilds dependents only when notifyListeners is called.ValueListenableProvider, a provider that rebuilds whenever the value passed to a ValueNotifier change.Consumer with up to 6 parameters.MultiProvider, a provider that makes a tree of provider more readableStreamProvider, a stream that exposes to its descendants the current value of a Stream.StatefulProvider with a modified prototype. The second argument of valueBuilder and didChangeDependencies have been removed. And valueBuilder is now called only once for the whole life-cycle of StatefulProvider.Consumer, useful when we need to both expose and consume a value simultaneously.HookProvider, a Provider that creates its value from a Hook.StatefulProvider. Either make a StatefulWidget or use HookProvider.Provider widget shows the current value.didChangeDependencies callback to allow updating the value based on an InheritedWidgetupdateShouldNotify method to both Provider and StatefulProvideronDispose has been added to StatefulProvidervalueBuilder callback