FutureProvider<T> constructor

FutureProvider<T>(
  1. Create<FutureOr<T>, FutureProviderRef<T>> _createFn,
  2. {String? name,
  3. Iterable<ProviderOrFamily>? dependencies,
  4. @Deprecated('Will be removed in 3.0.0') Family<Object?>? from,
  5. @Deprecated('Will be removed in 3.0.0') Object? argument,
  6. @Deprecated('Will be removed in 3.0.0') DebugGetCreateSourceHash? debugGetCreateSourceHash}
)

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:

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:

Implementation

FutureProvider(
  this._createFn, {
  super.name,
  super.dependencies,
  @Deprecated('Will be removed in 3.0.0') super.from,
  @Deprecated('Will be removed in 3.0.0') super.argument,
  @Deprecated('Will be removed in 3.0.0') super.debugGetCreateSourceHash,
}) : super(
        allTransitiveDependencies:
            computeAllTransitiveDependencies(dependencies),
      );