Skip to main content

.autoDispose

A common use-case when using providers is to want to destroy the state of a provider when it is no-longer used.

There are multiple reasons for doing such, such as:

  • When using Firebase, to close the connection and avoid unnecessary cost
  • To reset the state when the user leaves a screen and re-enters it.

Providers comes with a built-in support for such use-case, through the .autoDispose modifier.

Usage#

To tell Riverpod to destroy the state of a provider when it is no-longer used, simply append .autoDispose to your provider:

final userProvider = StreamProvider.autoDispose<User>((ref) {
});

That's it. Now, the state of userProvider will automatically be destroyed when it is no-longer used.

Note how the generic parameters are passed after autoDispose instead of before – autoDispose is not a named constructor.

note

You can combine .autoDispose with other modifiers if you need to:

final userProvider = StreamProvider.autoDispose.family<User, String>((ref, id) {
});

ref.maintainState#

Marking a provider with autoDispose also adds an extra property on ref: maintainState.

The maintainState property is a boolean (false by default) that allows the provider to tell Riverpod if the state of the provider should be preserved even if no-longer listened.

A use-case would be to set this flag to true after an HTTP request have completed:

final myProvider = FutureProvider.autoDispose((ref) async {
final response = await dio.get(...);
ref.maintainState = true;
return response;
});

This way, if the request failed and the user leaves the screen then re-enters it, then the request will be performed again. But if the request completed successfuly, the state will be preserved and re-entering the screen will not trigger a new request.

Example: Cancelling HTTP requests when no-longer used#

The autoDispose modifier could be combined with FutureProvider and ref.onDispose to easily cancel HTTP requests when they are no-longer needed.

The goal is:

  • Start an HTTP request when the user enters a screen
  • if the user leaves the screen before the request completed, cancels the HTTP request
  • if the request succeeded, leaving and re-entering the screen does not start a new request

In code, this would be:

final myProvider = FutureProvider.autoDispose((ref) async {
// An object from package:dio that allows cancelling http requests
final cancelToken = CancelToken();
// When the provider is destroyed, cancel the http request
ref.onDispose(() => cancelToken.cancel());
// Fetch our data and pass our `cancelToken` for cancellation to work
final response = await dio.get('path', cancelToken: cancelToken);
// If the request completed successfully, keep the state
ref.maintainState = true;
return response;
});

The argument type 'AutoDisposeProvider' can't be assigned to the parameter type 'AlwaysAliveProviderBase'#

When using .autoDispose, you may find yourself in a situation where your application does not compile with an error similar to:

The argument type 'AutoDisposeProvider' can't be assigned to the parameter type 'AlwaysAliveProviderBase'

Don't worry! This error is voluntary. It happens because you most likely have a bug:

You tried to listen to a provider marked with .autoDispose in a provider that is not marked with .autoDispose, such as:

final firstProvider = Provider.autoDispose((ref) => 0);
final secondProvider = Provider((ref) {
// The argument type 'AutoDisposeProvider<int>' can't be assigned to the
// parameter type 'AlwaysAliveProviderBase<Object, Null>'
ref.watch(firstProvider);
});

This is undesired, as it would cause firstProvider to never be disposed.

To fix, consider marking secondProvider with .autoDispose too:

final firstProvider = Provider.autoDispose((ref) => 0);
final secondProvider = Provider.autoDispose((ref) {
ref.watch(firstProvider);
});
Edit this page