AutoDisposeFutureProvider<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>>
• AutoDisposeFutureProvider

Constructors

AutoDisposeFutureProvider(Create<FutureOr<T>, AutoDisposeFutureProviderRef<T>> _createFn, {String? name, Iterable<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.

AutoDisposeFutureProvider.internal(Create<FutureOr<T>, AutoDisposeFutureProviderRef<T>> _createFn, {required String? name, required Iterable<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.

final, inherited

argument → Object?

If this provider was created with the .family modifier, argument is the variable that was used.

final, inherited

debugGetCreateSourceHash → DebugGetCreateSourceHash?

A debug-only fucntion for obtaining a hash of the source code of the initialization function.

final, inherited

dependencies → Iterable<ProviderOrFamily>?

The list of providers that this provider potentially depends on.

final, inherited

from → Family<Object?>?

If this provider was created with the .family modifier, from is the .family instance.

final, inherited

future → Refreshable<Future<T>>

Obtains the Future associated with a FutureProvider.

late, final

hashCode → int

The hash code for this object.

no setter, inherited

name → String?

A custom label for providers.

final, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

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() → AutoDisposeFutureProviderElement<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<T>, AutoDisposeFutureProviderRef<T>> create) → Override

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)) → ProviderListenable<Selected>

Partially listen to a provider.

inherited

selectAsync<Output>(Output selector(T data)) → ProviderListenable<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

family → const AutoDisposeFutureProviderFamily<R, Arg> Function<R, Arg>(FutureOr<R> _createFn(AutoDisposeFutureProviderRef<R> ref, Arg arg), {Iterable<ProviderOrFamily>? dependencies, String? name})

A group of providers that builds their value from an external parameter.