1# Riverpod State Management
2 
3## Provider Types
4 
5```dart
6import 'package:flutter_riverpod/flutter_riverpod.dart';
7 
8// Simple state
9final counterProvider = StateProvider<int>((ref) => 0);
10 
11// Async state (API calls)
12final usersProvider = FutureProvider<List<User>>((ref) async {
13  final api = ref.read(apiProvider);
14  return api.getUsers();
15});
16 
17// Stream state (real-time)
18final messagesProvider = StreamProvider<List<Message>>((ref) {
19  return ref.read(chatServiceProvider).messagesStream;
20});
21```
22 
23## Notifier Pattern (Riverpod 2.0)
24 
25```dart
26@riverpod
27class TodoList extends _$TodoList {
28  @override
29  List<Todo> build() => [];
30 
31  void add(Todo todo) {
32    state = [...state, todo];
33  }
34 
35  void toggle(String id) {
36    state = [
37      for (final todo in state)
38        if (todo.id == id) todo.copyWith(completed: !todo.completed) else todo,
39    ];
40  }
41 
42  void remove(String id) {
43    state = state.where((t) => t.id != id).toList();
44  }
45}
46 
47// Async Notifier
48@riverpod
49class UserProfile extends _$UserProfile {
50  @override
51  Future<User> build() async {
52    return ref.read(apiProvider).getCurrentUser();
53  }
54 
55  Future<void> updateName(String name) async {
56    state = const AsyncValue.loading();
57    state = await AsyncValue.guard(() async {
58      final updated = await ref.read(apiProvider).updateUser(name: name);
59      return updated;
60    });
61  }
62}
63```
64 
65## Usage in Widgets
66 
67```dart
68// ConsumerWidget (recommended)
69class TodoScreen extends ConsumerWidget {
70  const TodoScreen({super.key});
71 
72  @override
73  Widget build(BuildContext context, WidgetRef ref) {
74    final todos = ref.watch(todoListProvider);
75 
76    return ListView.builder(
77      itemCount: todos.length,
78      itemBuilder: (context, index) {
79        final todo = todos[index];
80        return ListTile(
81          title: Text(todo.title),
82          leading: Checkbox(
83            value: todo.completed,
84            onChanged: (_) => ref.read(todoListProvider.notifier).toggle(todo.id),
85          ),
86        );
87      },
88    );
89  }
90}
91 
92// Selective rebuilds with select
93class UserAvatar extends ConsumerWidget {
94  const UserAvatar({super.key});
95 
96  @override
97  Widget build(BuildContext context, WidgetRef ref) {
98    final avatarUrl = ref.watch(userProvider.select((u) => u?.avatarUrl));
99 
100    return CircleAvatar(
101      backgroundImage: avatarUrl != null ? NetworkImage(avatarUrl) : null,
102    );
103  }
104}
105 
106// Async state handling
107class UserProfileScreen extends ConsumerWidget {
108  @override
109  Widget build(BuildContext context, WidgetRef ref) {
110    final userAsync = ref.watch(userProfileProvider);
111 
112    return userAsync.when(
113      data: (user) => Text(user.name),
114      loading: () => const CircularProgressIndicator(),
115      error: (err, stack) => Text('Error: $err'),
116    );
117  }
118}
119```
120 
121## Quick Reference
122 
123| Provider | Use Case |
124|----------|----------|
125| `Provider` | Computed/derived values |
126| `StateProvider` | Simple mutable state |
127| `FutureProvider` | Async operations (one-time) |
128| `StreamProvider` | Real-time data streams |
129| `NotifierProvider` | Complex state with methods |
130| `AsyncNotifierProvider` | Async state with methods |
131