flutter-state-management

Flutter State Management

Overview

Widgets render state; something else owns it. Keeping business logic and data out of the widget tree is what makes Flutter screens testable and rebuilds cheap.

Core principle: Follow the app's existing state solution (Riverpod, Bloc, Provider, etc.) — do not introduce a second one. The pattern matters more than the library.

Rules (library-agnostic)

• One source of truth per piece of state, owned by a controller/notifier/bloc — never duplicated across widgets via setState.
• Presentation ↔ state via a thin interface: the widget watches state and sends events/intents; it never contains the business rule or the network call.
• StatefulWidget is for ephemeral UI only (animation controllers, focus, scroll) — anything that outlives a rebuild or comes from a service is app state.
• Handle all async states explicitly: loading, data, empty, error. A FutureBuilder/AsyncValue that only renders the happy path ships a spinner-forever bug.
• Dispose controllers/subscriptions to avoid leaks.
• Immutable state objects (copyWith) so rebuilds are diff-friendly and predictable.

Worked Example — Riverpod 3 (Notifier/AsyncNotifier, not StateNotifier)

StateNotifier/StateNotifierProvider/StateProvider/ChangeNotifierProvider are legacy as of Riverpod 3 — use Notifier/AsyncNotifier in new code. If the repo still uses StateNotifier, follow it; don't migrate existing code on your own initiative.

// state owner: no widgets, pure logic — unit-testable without pumping a widget
class TaskListNotifier extends AsyncNotifier<List<Task>> {
  @override
  Future<List<Task>> build() => ref.read(taskRepositoryProvider).list();

  Future<void> reload() async {
    state = const AsyncLoading();
    state = await AsyncValue.guard(() => ref.read(taskRepositoryProvider).list());
  }
}

final taskListProvider = AsyncNotifierProvider<TaskListNotifier, List<Task>>(TaskListNotifier.new);

// widget: watches state, renders each case, sends intents — no logic
ref.watch(taskListProvider).when(
  loading: () => const AppSpinner(),
  error:   (e, _) => AppErrorView(message: e.toString(), onRetry: () => ref.read(taskListProvider.notifier).reload()),
  data:    (tasks) => tasks.isEmpty ? const EmptyView() : TaskList(tasks: tasks),
);