FutureProvider<T> class
A provider that asynchronously creates a value.
FutureProvider can be considered as a combination of Provider and
FutureBuilder
.
By using FutureProvider, the UI will be able to read the state of the
future synchronously, handle the loading/error states, and rebuild when the
future completes.
A common use-case for FutureProvider is to represent an asynchronous operation such as reading a file or making an HTTP request, that is then listened to by the UI.
It can then be combined with:
- FutureProvider.family, to parameterize the http request based on external
parameters, such as fetching a
User
from its id. - FutureProvider.autoDispose, to cancel the HTTP request if the user leaves the screen before the Future completed.
Usage example: reading a configuration file
FutureProvider can be a convenient way to expose a Configuration
object
created by reading a JSON file.
Creating the configuration would be done with your typical async/await syntax, but inside the provider. Using Flutter's asset system, this would be:
final configProvider = FutureProvider<Configuration>((ref) async {
final content = json.decode(
await rootBundle.loadString('assets/configurations.json'),
) as Map<String, Object?>;
return Configuration.fromJson(content);
});
Then, the UI can listen to configurations like so:
Widget build(BuildContext context, WidgetRef ref) {
AsyncValue<Configuration> config = ref.watch(configProvider);
return config.when(
loading: () => const CircularProgressIndicator(),
error: (err, stack) => Text('Error: $err'),
data: (config) {
return Text(config.host);
},
);
}
This will automatically rebuild the UI when the Future completes.
As you can see, listening to a FutureProvider inside a widget returns an AsyncValue – which allows handling the error/loading states.
See also:
- AsyncNotifierProvider, similar to FutureProvider but also enables modifying the state from the UI.
- Provider, a provider that synchronously creates a value
- StreamProvider, a provider that asynchronously exposes a value that can change over time.
- FutureProvider.family, to create a FutureProvider from external parameters
- FutureProvider.autoDispose, to destroy the state of a FutureProvider when no longer needed.
- Inheritance
-
- Object
- ProviderOrFamily
- ProviderBase<
AsyncValue< T> > - FutureProvider
- Mixed-in types
Constructors
-
FutureProvider(Create<
FutureOr< _createFn, {String? name, Iterable<T> , FutureProviderRef<T> >ProviderOrFamily> ? dependencies, @Deprecated('Will be removed in 3.0.0') Family<Object?> ? from, @Deprecated('Will be removed in 3.0.0') Object? argument, @Deprecated('Will be removed in 3.0.0') DebugGetCreateSourceHash? debugGetCreateSourceHash}) - A provider that asynchronously creates a value.
-
FutureProvider.internal(Create<
FutureOr< _createFn, {required String? name, required Iterable<T> , FutureProviderRef<T> >ProviderOrFamily> ? dependencies, required Iterable<ProviderOrFamily> ? allTransitiveDependencies, required DebugGetCreateSourceHash? debugGetCreateSourceHash, Family<Object?> ? from, Object? argument}) - An implementation detail of Riverpod
Properties
-
allTransitiveDependencies
→ Iterable<
ProviderOrFamily> ? -
All the dependencies of a provider and their dependencies too.
finalinherited
- argument → Object?
-
If this provider was created with the
.family
modifier, argument is the variable that was used.finalinherited - debugGetCreateSourceHash → DebugGetCreateSourceHash?
-
A debug-only fucntion for obtaining a hash of the source code of the
initialization function.
finalinherited
-
dependencies
→ Iterable<
ProviderOrFamily> ? -
The list of providers that this provider potentially depends on.
finalinherited
-
from
→ Family<
Object?> ? -
If this provider was created with the
.family
modifier, from is the.family
instance.finalinherited -
future
→ AlwaysAliveRefreshable<
Future< T> > -
Obtains the
Future
associated with a FutureProvider.latefinal - hashCode → int
-
The hash code for this object.
no setterinherited
- name → String?
-
A custom label for providers.
finalinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
addListener(
Node node, void listener(AsyncValue< T> ? previous, AsyncValue<T> next), {required void onError(Object error, StackTrace stackTrace)?, required void onDependencyMayHaveChanged()?, required bool fireImmediately}) → ProviderSubscription<AsyncValue< T> > -
Starts listening to this transformer
inherited
-
createElement(
) → FutureProviderElement< T> -
An internal method that defines how a provider behaves.
override
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
overrideWith(
Create< FutureOr< create) → OverrideT> , FutureProviderRef<T> > - Override the provider with a new initialization function.
-
read(
Node node) → AsyncValue< T> -
Obtains the result of this provider expression without adding listener.
inherited
-
select<
Selected> (Selected selector(AsyncValue< T> value)) → AlwaysAliveProviderListenable<Selected> -
Partially listen to a provider.
inherited
-
selectAsync<
Output> (Output selector(T data)) → AlwaysAliveProviderListenable< Future< Output> > -
A variant of select for asynchronous values
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Constants
- autoDispose → const AutoDisposeFutureProviderBuilder
- Marks the provider as automatically disposed when no longer listened to.
- family → const FutureProviderFamilyBuilder
- A group of providers that builds their value from an external parameter.