FutureProvider<State> 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 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.

Constructors

FutureProvider(Create<FutureOr<State>, FutureProviderRef<State>> _create, {String? name, List<ProviderOrFamily>? dependencies, Family<dynamic, dynamic, ProviderBase>? from, Object? argument}): A provider that asynchronously creates a single value.

Properties

allTransitiveDependencies → List<ProviderOrFamily>?: All the dependencies of a provider and their dependencies too.
latefinalinherited
argument → Object?: If this provider was created with the .family modifier, argument is variable used.
finalinherited
dependencies → List<ProviderOrFamily>?: The list of providers that this provider potentially depends on.
final
from → Family<dynamic, dynamic, ProviderBase>?: If this provider was created with the .family modifier, from is the .family instance.
finalinherited
future → AlwaysAliveProviderBase<Future<State>>: A provider that exposes the Future created by a FutureProvider.
latefinal
hashCode → int: The hash code for this object.
no setterinherited
name → String?: A custom label for providers.
finalinherited
originProvider → ProviderBase<AsyncValue<State>>: The provider that will be refreshed when calling ProviderContainer.refresh and that will be overridden when passed to ProviderScope.
no setteroverride
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

create(covariant FutureProviderElement<State> ref) → AsyncValue<State>: Initializes the state of a provider
override
createElement() → FutureProviderElement<State>: An internal method that defines how a provider behaves.
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
overrideWithProvider(AlwaysAliveProviderBase<AsyncValue<State>> value) → Override: Overrides a provider with a value, ejecting the default behaviour.
inherited
overrideWithValue(AsyncValue<State> value) → Override: Overrides a provider with a value, ejecting the default behaviour.
inherited
select<Selected>(Selected selector(AsyncValue<State> value)) → AlwaysAliveProviderListenable<Selected>: Partially listen to a provider.
inherited
toString() → String: A string representation of this object.
inherited
updateShouldNotify(AsyncValue<State> previousState, AsyncValue<State> newState) → bool: Called when a provider is rebuilt. Used for providers to not notify their listeners if the exposed value did not change.
override

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.