StateNotifierProvider: Manage Immutable State

Why it exists

When state becomes more than a simple value (e.g., a list of items, user settings), managing its changes can get messy. StateNotifier was created to centralize the modification logic for a single piece of complex, immutable state, preventing bugs and separating business logic from the UI.

The mental model

Think of a StateNotifier as a vault for your state object. The StateNotifierProvider gives your UI a key to the vault's front desk, not the vault itself. You can ask the clerk (the notifier) to perform specific, pre-approved actions like addTodo or removeTodo, but you can't walk in and change the contents yourself. The state object inside is immutable; the clerk always replaces the old one with a brand new one.

How it works

You define a class that extends StateNotifier and holds an immutable state object. This class exposes public methods that are the only way to change the state. Inside these methods, you create a new instance of the state object with the desired changes and assign it to the state property. A global StateNotifierProvider then creates an instance of your notifier. In the UI, ref.watch(myProvider) listens for changes and rebuilds, while ref.read(myProvider.notifier).myMethod() calls your logic without causing a rebuild.

When to use it

Use it for managing self-contained, complex state with its own business logic, like a shopping cart, a filtered list, or form data. It excels at keeping your state modification rules in one place. While still common, note that the modern Riverpod recommendation is to prefer NotifierProvider, which offers a similar pattern with more features.

When not to use it

For simple state like a boolean or a counter, StateProvider is much simpler. For data fetched from an API or database, FutureProvider or StreamProvider are more direct. If your state object is mutable by design, ChangeNotifierProvider is the correct tool for that pattern.

One canonical example

A todo list. The state is List<Todo>. A TodosNotifier class extends StateNotifier<List<Todo>> and has a method addTodo(Todo newTodo). The correct implementation is state = [...state, newTodo];, which creates a new list. The common mistake is to write state.add(newTodo). This mutates the existing list in memory, and because the object reference for state hasn't changed, Riverpod won't detect the update and the UI will not rebuild.