FutureProvider<T> class
A provider that asynchronously creates a single 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 by the UI.
It can then be combined with:
- FutureProvider.family, for parameterizing 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, ScopedReader watch) {
AsyncValue<Configuration> config = 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:
- Provider, a provider that synchronously creates a value
- StreamProvider, a provider that asynchronously expose a value which 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
- ProviderBase<
Future< T> , AsyncValue<T> > - RootProvider<
Future< T> , AsyncValue<T> > - AlwaysAliveProviderBase<
Future< T> , AsyncValue<T> > - FutureProvider
- Annotations
-
- @sealed
Constructors
-
FutureProvider(Create<
Future< _create, {String? name})T> , ProviderReference> - A provider that asynchronously creates a single value.
Properties
- argument → Object?
-
If this provider was created with the
.family
modifier, argument is variable used.no setterinherited - debugId ↔ String
-
A unique identifier for this provider, used by devtools to differentiate providers
latefinalinherited
-
from
→ Family<
dynamic, dynamic, dynamic, ProviderReference, RootProvider> ? -
If this provider was created with the
.family
modifier, from is the.family
instance.no setterinherited -
future
→ AlwaysAliveProviderBase<
Future< T> , Future<T> > -
A provider that exposes the
Future
created by a FutureProvider.no setter - 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
-
create(
covariant ProviderReference ref) → Future< T> -
override
-
createElement(
) → ProviderElement< Future< T> , AsyncValue<T> > -
An internal method that defines how a provider behaves.
inherited
-
createState(
) → _FutureProviderState< T> -
An internal method that creates the state of a provider.
override
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
overrideWithProvider(
AlwaysAliveProviderBase< Object?, AsyncValue< provider) → ProviderOverrideT> > -
Overrides the behavior of this provider with another provider.
inherited
-
overrideWithValue(
AsyncValue< T> value) → Override -
inherited
-
select<
Selected> (Selected selector(AsyncValue< T> value)) → ProviderListenable<Selected> -
Partially listen to a provider.
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.
- family → const FutureProviderFamilyBuilder
- A group of providers that builds their value from an external parameter.