The autoDispose Modifier

This is Part 3 of Mastering Riverpod: Core Concepts. By default, a provider's state lives forever — once created, it stays cached in the ProviderContainer (Foundation Part 3) for the app's lifetime. That's great for caching, but a problem for state tied to a specific screen or argument. The autoDispose modifier flips this: it destroys a provider's state when nothing is watching it anymore. Understanding it is the key to memory management in Riverpod.

The default: providers live forever

A normal provider is created lazily on first watch and then never disposed (until the whole ProviderScope goes away):

final userProvider = FutureProvider<User>((ref) => fetchUser());

Open a screen that watches userProvider, navigate away, come back — the cached User is still there (great, no refetch). But this also means: if you have a per-screen provider, or a family with many arguments, those instances pile up in memory even after their screens are gone. That's a leak.

autoDispose: destroy when unwatched

Marking a provider autoDispose tells Riverpod: "when the last listener stops watching this, destroy its state."

// 3.0 manual syntax — the isAutoDispose named parameter:
final userProvider = FutureProvider<User>(
  isAutoDispose: true,
  (ref) => fetchUser(),
);

// Equivalent modifier form (also used with .family):
final userProvider = FutureProvider.autoDispose<User>((ref) => fetchUser());

Now when the screen watching userProvider is disposed and no one else watches it, Riverpod tears down the state. Re-open the screen later and it's recreated fresh (a new fetch). The trade-off in one line:

autoDispose trades caching for cleanup. Keep-forever (default) = cached, fast re-entry, more memory. autoDispose = fresh each time, less memory, possible refetch. Choose per provider based on what the data needs.

Code-gen note: with @riverpod code generation (a later series), providers are autoDispose by default — you opt out with @Riverpod(keepAlive: true). Manual providers are keep-alive by default and you opt in. Don't let that asymmetry surprise you.

The disposal lifecycle

autoDispose doesn't fire the instant the last widget unmounts — it's careful to avoid disposing during a quick rebuild. The precise sequence (per the docs):

last listener removed
   → ref.onCancel fires
   → Riverpod waits one frame
   → if STILL unwatched → ref.onDispose fires → state destroyed
   (if a new listener appears within that frame → ref.onResume, state kept)

That one-frame grace period is important: when you navigate between screens (or a widget rebuilds), the provider may briefly have zero listeners and then a new one — Riverpod won't dispose in that gap. So autoDispose is safe for normal navigation; it only tears down when the provider is genuinely unused. We cover onCancel/onResume/onDispose fully in Part 7.

Why families need autoDispose

This is the most important use case. Recall from Part 2 that a family caches one instance per argument. Without autoDispose, every argument you ever pass leaves a cached instance behind forever:

// ❌ Each distinct id leaks a cached User provider forever.
final userProvider = FutureProvider.family<User, String>((ref, id) => fetchUser(id));

// ✅ Instances are destroyed when their screen stops watching them.
final userProvider =
    FutureProvider.autoDispose.family<User, String>((ref, id) => fetchUser(id));

Scroll through 500 user profiles with the first version and you cache 500 User providers. With autoDispose, each is cleaned up when you scroll past it. Families should almost always be autoDispose — it's the single most common place this modifier matters.

Typical candidates (and non-candidates)

| Good fit for autoDispose | Better as keep-alive (default) | | --- | --- | | per-screen detail data (user by id, product by id) | app-wide singletons (auth state, theme, config) | | search results / query-parameterized state | reference data fetched once and reused everywhere | | any family with many arguments | expensive data you want cached across navigation | | state that should reset when you leave a screen | DI services/repositories (Provider for a Dio) |

A useful instinct: "Is this data tied to a screen/argument that comes and goes? → autoDispose. Is it app-wide and worth caching? → keep-alive."

autoDispose is the foundation for cleanup and caching control

Two important features build on top of autoDispose:

• ref.onDispose (Part 7) — run cleanup (cancel timers, close controllers) when the state is destroyed. Especially relevant for autoDispose providers, which actually get destroyed during normal use.
• ref.keepAlive (Part 4) — selectively keep an autoDispose provider alive (e.g. only after a successful fetch, or for a cache duration). This gives you fine-grained "auto-dispose unless…" control.

So autoDispose isn't just on/off — it's the base that lets you express nuanced caching policies. We'll build those next.

Practice Challenges

Challenge 1 — Make one autoDispose. Convert final p = FutureProvider<User>((ref) => fetch()); to autoDispose (modifier form).

final p = FutureProvider.autoDispose<User>((ref) => fetch());
// or: FutureProvider<User>(isAutoDispose: true, (ref) => fetch());

Challenge 2 — Family memory. Why does a non-autoDispose family<User, String> leak, and what fixes it?

Challenge 3 — Choose the policy. autoDispose or keep-alive for: (a) auth state, (b) a product-detail-by-id provider, (c) app theme, (d) search results?

Challenge 4 — Disposal timing. Does an autoDispose provider get destroyed the instant its widget unmounts? Explain.

Challenge 5 — Code-gen default. With @riverpod code generation, is a provider autoDispose or keep-alive by default, and how do you change it?

Questions to test yourself

Q1 (basic). What does autoDispose do?

Q2 (basic). What's the default disposal behavior of a manual provider (no modifier)?

Q3 (intermediate). What's the trade-off autoDispose makes?

Q4 (intermediate). Walk through the autoDispose lifecycle when the last listener leaves.

Q5 (intermediate). Why do family providers almost always need autoDispose?

Q6 (advanced). How does autoDispose enable nuanced caching policies rather than just on/off?

Wrapping up

autoDispose is Riverpod's memory-management lever:

• By default providers are keep-alive (cached forever); autoDispose destroys state when no listeners remain.
• The lifecycle: last listener → onCancel → wait one frame → onDispose (destroy) — with a grace period so navigation/rebuilds are safe.
• It trades caching for cleanup — pick per provider (per-screen/argument → autoDispose; app-wide → keep-alive).
• Families almost always need it to avoid accumulating per-argument instances.
• Code-gen providers are autoDispose by default (opt out with keepAlive: true); manual ones are the reverse.

autoDispose is all-or-nothing per provider — but sometimes you want "auto-dispose, but keep this one alive once I've fetched it." That selective control is keepAlive. Part 4 covers keepAlive — when you don't want your provider to die.