riverpod-auto-dispose

Riverpod — Automatic disposal

Instructions

With automatic disposal enabled, Riverpod destroys a provider's state when it has no listeners for one frame. This frees memory and stops work (e.g. network requests) when the provider is no longer used.

Enabling

• Code generation: Enabled by default. Disable with @Riverpod(keepAlive: true).
• Manual: Add isAutoDispose: true when creating the provider (e.g. Provider.autoDispose(...) or FutureProvider.autoDispose(...)).

// Codegen: disable auto-dispose
@Riverpod(keepAlive: true)
String helloWorld(Ref ref) => 'Hello world!';

// Manual: enable
final helloWorldProvider = Provider<String>(
  isAutoDispose: true,
  (ref) => 'Hello world!',
);

When a provider has parameters (family), enable auto-dispose to avoid caching every parameter combination forever and causing memory leaks.

When disposal runs

Riverpod counts listeners (from ref.watch, ref.listen, etc.). When the count reaches zero, it waits one frame; if still zero, ref.onCancel runs, then the state is destroyed and ref.onDispose runs.

Reacting to disposal: ref.onDispose

Register a callback when the state is destroyed (e.g. close a StreamController):

final provider = StreamProvider<int>((ref) {
  final controller = StreamController<int>();
  ref.onDispose(controller.close);
  return controller.stream;
});

Do not trigger side effects that modify other providers inside onDispose. You can call onDispose multiple times. Other lifecycles: ref.onCancel (last listener removed), ref.onResume (new listener added after cancel).

Forcing destruction: ref.invalidate

From a widget or another provider, call ref.invalidate(provider) to destroy the current state. If the provider is still listened to, it will recompute; otherwise it stays destroyed until read again.

onPressed: () => ref.invalidate(someProvider),

For family providers you can invalidate one parameter combination or all (see riverpod-family and docs).