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, dynamic>;

  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:

Inheritance
Annotations

Constructors

FutureProvider(Create<Future<T>, ProviderReference> create, {String name})
A provider that asynchronously creates a single value. [...]

Properties

argument Object
If this provider was created with the .family modifier, argument is variable used.
read-only, inherited
from Family<dynamic, dynamic, dynamic, ProviderReference, RootProvider>
If this provider was created with the .family modifier, from is the .family instance.
read-only, inherited
future AlwaysAliveProviderBase<Future<T>, Future<T>>
A provider that exposes the Future created by a FutureProvider. [...]
read-only
hashCode int
The hash code for this object. [...]
@nonVirtual, read-only, inherited
name String
{@template riverpod.name} A custom label for providers. [...]
final, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited

Methods

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 non-existent method or property is accessed. [...]
inherited
overrideWithProvider(AlwaysAliveProviderBase<Future<T>, AsyncValue<T>> provider) → ProviderOverride
Overrides the behavior of this provider with another provider. [...]
inherited
overrideWithValue(AsyncValue<T> value) Override
Overrides the behavior of a provider with a value. [...]
inherited
select<Selected>(Selected selector(AsyncValue<T> value)) ProviderListenable<Selected>
Partially listen to a provider. [...]
inherited
toString() String
Returns 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. [...]
const AutoDisposeFutureProviderBuilder()
family → const FutureProviderFamilyBuilder
A group of providers that builds their value from an external parameter. [...]
const FutureProviderFamilyBuilder()