Riverpod: Compile-Safe, Reactive State Management

Why it exists

State management in Flutter can involve significant boilerplate, especially for asynchronous operations and sharing state between distant widgets. Riverpod was created to offer a compile-safe, declarative, and testable way to manage state that is decoupled from the widget tree, simplifying common patterns.

The mental model

Think of Riverpod providers like cells in a spreadsheet. Some cells hold raw data (a counter), while others contain formulas that depend on other cells (a filtered list). When the raw data changes, any formula cell that depends on it automatically recalculates. In Riverpod, your widgets are like charts that display this data; they automatically update when the underlying provider values change.

How it works

You declare providers using the @riverpod annotation. A provider is an object that exposes a piece of state. Inside a widget, you use a WidgetRef to interact with providers. Calling ref.watch(myProvider) subscribes the widget to that provider's state. Whenever the state changes, the widget automatically rebuilds. For async tasks, providers return an AsyncValue (AsyncData, AsyncError, or a loading state), letting you cleanly handle all cases in the UI. Providers can also watch other providers, creating a chain of reactive dependencies.

When to use it

Use Riverpod as a primary state management solution in Flutter or Dart apps. It is ideal for fetching and caching remote data, managing user input that drives UI changes (like a search query), and sharing application-wide state like themes or authentication status. Its declarative nature makes complex patterns like "pull-to-refresh" or "search-as-you-type" much simpler to implement.

When not to use it

For extremely simple apps with minimal state, Riverpod might be overkill. State that is truly ephemeral and local to a single widget (like animation controllers or simple form field values) can often be handled more directly with a StatefulWidget's local state.

One canonical example

A common use case is a filtered to-do list. You would have one provider for the full list of todos and another for the current filter setting (e.g., 'all', 'completed'). A third provider, filteredTodosProvider, would watch both of these. Its job is to return a new list based on the current filter. A widget would then watch(filteredTodosProvider) and automatically rebuild with the correct list whenever the master list changes or the user selects a new filter, with no manual listeners required.