Riverpod

https://riverpod.dev/docs/
Admin
Riverpod is a reactive caching and data-binding framework for Dart and Flutter that enables...
Tokens:82,542
Snippets:683
Trust Score:9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Check Riverpod CLI help

Source: https://riverpod.dev/docs/migration/0.14.0_to_1.0.0

After installing the migration tool, run this command to verify the installation and see available options.

```bash
riverpod --help
```

--------------------------------

### Install riverpod_cli

Source: https://riverpod.dev/docs/migration/0.13.0_to_0.14.0

Command to install the Riverpod migration CLI tool.

```bash
dart pub global activate riverpod_cli  

```

--------------------------------

### Run riverpod migrate

Source: https://riverpod.dev/docs/migration/0.13.0_to_0.14.0

Command to start the migration process on your project.

```bash
riverpod migrate  

```

--------------------------------

### Check riverpod_cli installation

Source: https://riverpod.dev/docs/migration/0.13.0_to_0.14.0

Command to verify the CLI tool is installed and available.

```bash
riverpod --help  

```

--------------------------------

### Example migration suggestion

Source: https://riverpod.dev/docs/migration/0.13.0_to_0.14.0

An example of the suggested change the migration tool may propose, showing the old and new lines.

```diff
Widget build(BuildContext context, ScopedReader watch) {  
-  MyModel state = watch(provider.state);  
+  MyModel state = watch(provider);  
}  
  
Accept change (y = yes, n = no [default], A = yes to all, q = quit)?   

```

--------------------------------

### StateProvider example

Source: https://riverpod.dev/docs/migration/from_state_notifier

Shows the old StateProvider pattern for a simple counter. This is deprecated and should be migrated to Notifier.

```dart
final counterProvider = StateProvider<int>((ref) {  
  return 0;  
});  
```

--------------------------------

### Example migration suggestion output

Source: https://riverpod.dev/docs/migration/0.14.0_to_1.0.0

The migration tool analyzes your project and suggests changes like this. You can accept or reject each change interactively.

```diff
-Widget build(BuildContext context, ScopedReader watch) {
+Widget build(BuildContext context, Widget ref) {
-  MyModel state = watch(provider);
+  MyModel state = ref.watch(provider);
}

Accept change (y = yes, n = no [default], A = yes to all, q = quit)?
```

--------------------------------

### Testing providers with ProviderContainer.test()

Source: https://riverpod.dev/docs/concepts2/containers

Creates a fresh ProviderContainer for each test so provider state starts clean. The example reads the initial counter value, increments it, and verifies the updated value, then checks that the counter cannot go below zero.

```dart
test('Counter starts at 0 and can be incremented', () {  
  final container = ProviderContainer.test();  
  
  expect(container.read(counterProvider), 0);  
  container.read(counterProvider.notifier).increment();  
  expect(container.read(counterProvider), 1);  
});  
  
test('Counter cannot go below 0', () {  
  final container = ProviderContainer.test();  
  
  expect(container.read(counterProvider), 0);  
  container.read(counterProvider.notifier).decrement();  
  expect(container.read(counterProvider), -1);  
});
```

--------------------------------

### Create a Storage with JsonSqFliteStorage for SQFlite (manual and codegen)

Source: https://riverpod.dev/docs/concepts2/offline

Install riverpod_sqflite and sqflite with `dart pub add`, then create a Storage instance for offline persistence. The example shows two implementations: one using `FutureProvider` (manual) and one using `@riverpod` with code generation (riverpod_generator). Both open a SQFlite database named 'riverpod.db' using `JsonSqFliteStorage.open`, sharing the storage instance between providers. Note: Riverpod's offline persistence is a simple wrapper around databases, not a full database replacement.

```bash
dart pub add riverpod_sqflite sqflite  

```

```dart
import 'package:flutter_riverpod/experimental/persist.dart';  
import 'package:flutter_riverpod/flutter_riverpod.dart';  
import 'package:path/path.dart';  
import 'package:riverpod_sqflite/riverpod_sqflite.dart';  
import 'package:sqflite/sqflite.dart';  
  
final storageProvider = FutureProvider<Storage<String, String>>((ref) async {  
  // Initialize SQFlite. We should share the Storage instance between providers.  
  return JsonSqFliteStorage.open(  
    join(await getDatabasesPath(), 'riverpod.db'),  
  );  
});  

```

```dart
import 'package:flutter_riverpod/experimental/persist.dart';  
import 'package:path/path.dart';  
import 'package:riverpod_annotation/riverpod_annotation.dart';  
import 'package:riverpod_sqflite/riverpod_sqflite.dart';  
import 'package:sqflite/sqflite.dart';  
  
part 'codegen.g.dart';  
  
@riverpod  
Future<Storage<String, String>> storage(Ref ref) async {  
  // Initialize SQFlite. We should share the Storage instance between providers.  
  return JsonSqFliteStorage.open(  
    join(await getDatabasesPath(), 'riverpod.db'),  
  );  
}  

```

--------------------------------

### Example: Storing selected book in provider

Source: https://riverpod.dev/docs/root/do_dont

Shows a provider that stores the currently selected book, which can cause issues with navigation history.

```dart
final selectedBookProvider = StateProvider<String?>((ref) => null);  
```

--------------------------------

### Example log output

Source: https://riverpod.dev/docs/concepts2/observers

Shows the output of the logger when a provider's value is updated. The log includes the provider name and new value.

```text
{  
  "provider": "Provider<int>",  
  "newValue": "1"  
}  

```

--------------------------------

### Hello world with flutter_hooks and hooks_riverpod

Source: https://riverpod.dev/docs/introduction/getting_started

Flutter example using `package:hooks_riverpod` with `flutter_hooks`. Demonstrates using `HookConsumerWidget` to combine hooks (e.g., `useState`) with `ref.watch` on a provider, all within a `ProviderScope`.

```dart
import 'package:flutter_hooks/flutter_hooks.dart';  
import 'package:hooks_riverpod/hooks_riverpod.dart';  
import 'package:material_ui/material_ui.dart';  
  
// We create a "provider", which will store a value (here "Hello world").  
// By using a provider, this allows us to mock/override the value exposed.  
final helloWorldProvider = Provider((_) => 'Hello world');  
  
void main() {  
  runApp(  
    // For widgets to be able to read providers, we need to wrap the entire  
    // application in a "ProviderScope" widget.  
    // This is where the state of our providers will be stored.  
    ProviderScope(  
      child: MyApp(),  
    ),  
  );  
}  
  
// Extend HookConsumerWidget instead of HookWidget, which is exposed by Riverpod  
class MyApp extends HookConsumerWidget {  
  @override  
  Widget build(BuildContext context, WidgetRef ref) {  
    // We can use hooks inside HookConsumerWidget  
    final counter = useState(0);  
  
    final String value = ref.watch(helloWorldProvider);  
  
    return MaterialApp(  
      home: Scaffold(  
        appBar: AppBar(title: const Text('Example')),  
        body: Center(  
          child: Text('$value ${counter.value}'),  
        ),  
      ),  
    );  
  }  
}  

```

--------------------------------

### Example: Navigation history with selected book

Source: https://riverpod.dev/docs/root/do_dont

Illustrates a navigation history scenario where using a provider for selected book can lead to incorrect back button behavior.

```text
/books  
/books/42  
/books/21  
```

--------------------------------

### Riverpod 2.0 auto-dispose async gap example (manual providers)

Source: https://riverpod.dev/docs/whats_new

Shows the problematic behavior in Riverpod 2.0 where an auto-dispose provider is disposed during an async gap. The example uses manual providers and prints 'disposed' every second.

```dart
final autoDisposeProvider = StreamProvider.autoDispose<int>((ref) {  
  ref.onDispose(() => print('disposed'));  
  ref.onCancel(() => print('paused'));  
  ref.onResume(() => print('resumed'));  
  // A stream that emits a value every second  
  return Stream.periodic(Duration(seconds: 1), (i) => i);  
});  
  
final asynchronousExampleProvider = FutureProvider<int>((ref) async {  
  print('Before async gap');  
  // An async gap inside a provider ; typically an API call.  
  // This will dispose the "autoDispose" provider  
  // before the async operation is completed  
  await null;  
    
  print('after async gap');  
  // We listen to our auto-dispose provider  
  // after the async operation  
  return ref.watch(autoDisposeProvider.future);  
});  
  
void main() {  
  final container = ProviderContainer();  
  // This will print 'disposed' every second,  
  // and will constantly print 0  
  container.listen(asynchronousExampleProvider, (_, value) {  
    if (value is AsyncData) print('${value.value}\n----');  
  });  
}  

```

--------------------------------

### Hello world with riverpod_generator (Flutter)

Source: https://riverpod.dev/docs/introduction/getting_started

Flutter example using `riverpod_generator` with `@riverpod` annotation to define a provider. Requires a part file `main.g.dart` and uses `ConsumerWidget` with `ref.watch` inside a `ProviderScope`.

```dart
import 'package:flutter_riverpod/flutter_riverpod.dart';  
import 'package:material_ui/material_ui.dart';  
import 'package:riverpod_annotation/riverpod_annotation.dart';  
  
part 'main.g.dart';  
  
// We create a "provider", which will store a value (here "Hello world").  
// By using a provider, this allows us to mock/override the value exposed.  
@riverpod  
String helloWorld(Ref ref) {  
  return 'Hello world';  
}  
  
void main() {  
  runApp(  
    // For widgets to be able to read providers, we need to wrap the entire  
    // application in a "ProviderScope" widget.  
    // This is where the state of our providers will be stored.  
    ProviderScope(  
      child: MyApp(),  
    ),  
  );  
}  
  
// Extend ConsumerWidget instead of StatelessWidget, which is exposed by Riverpod  
class MyApp extends ConsumerWidget {  
  @override  
  Widget build(BuildContext context, WidgetRef ref) {  
    final String value = ref.watch(helloWorldProvider);  
  
    return MaterialApp(  
      home: Scaffold(  
        appBar: AppBar(title: const Text('Example')),  
        body: Center(  
          child: Text(value),  
        ),  
      ),  
    );  
  }  
}  

```

--------------------------------

### Incorrect parameter example for family provider

Source: https://riverpod.dev/docs/concepts2/family

This example is incorrect because [1, 2, 3] != [1, 2, 3] due to list equality. Use riverpod_lint with the provider_parameters rule to catch this mistake.

```dart
// Incorrect parameter, as `[1, 2, 3] != [1, 2, 3]`  
ref.watch(myProvider([1, 2, 3]));  
```

--------------------------------

### Define a provider with riverpod

Source: https://riverpod.dev/docs/how_to/testing

An eagerly initialized FutureProvider that returns 'Hello world'. This is the provider to be mocked in the examples.

```dart
// An eagerly initialized provider.  
final exampleProvider = FutureProvider<String>((ref) async => 'Hello world');  

```

--------------------------------

### NotifierProvider.overrideWithBuild (generated provider)

Source: https://riverpod.dev/docs/whats_new

Same as the manual example but using the generated provider from riverpod_generator.

```dart
@riverpod  
class MyNotifier extends _$MyNotifier {  
  @override  
  int build() => 0;  
  
  void increment() {  
    state++;  
  }  
}  
  
void main() {  
  final container = ProviderContainer.test(  
    overrides: [  
      myProvider.overrideWithBuild((ref, self) {  
        // Mock the build method to start at 42.  
        // The "increment" method is unaffected.  
        return 42;  
      }),  
    ],  
  );  
}  

```

--------------------------------

### New Notifier syntax (non-codegen)

Source: https://riverpod.dev/docs/migration/from_state_notifier

The same counter example rewritten with the new Notifier API. The build method initializes the state and the provider is created with NotifierProvider.

```dart
class CounterNotifier extends Notifier<int> {  
  @override  
  int build() => 0;  
  
  void increment() => state++;  
  void decrement() => state++;  
}  
  
final counterNotifierProvider = NotifierProvider<CounterNotifier, int>(CounterNotifier.new);  

```

--------------------------------

### Full widget test example

Source: https://riverpod.dev/docs/how_to/testing

Complete widget test that pumps a ProviderScope, obtains a ProviderContainer via tester.container(), and reads a provider to assert its value.

```dart
void main() {  
  testWidgets('Some description', (tester) async {  
    await tester.pumpWidget(  
      const ProviderScope(child: YourWidgetYouWantToTest()),  
    );  
  
    final container = tester.container();  
  
    // TODO interact with your providers  
    expect(  
      container.read(provider),  
      'some value',  
    );  
  });  
}  

```

--------------------------------

### Example of ProviderException from failed dependency (riverpod)

Source: https://riverpod.dev/docs/concepts2/retry

Shows a provider that fails and another that depends on it, causing a ProviderException.

```dart
final failedProvider = Provider<int>(  
  (ref) => throw Exception('This provider always fails'),  
);  
  
final myProvider = Provider<int>(  
  // This provider depends on a failed provider,  
  // and will therefore throw a ProviderException  
  (ref) => ref.watch(failedProvider),  
);  

```

--------------------------------

### Example of ProviderException from failed dependency (riverpod_generator)

Source: https://riverpod.dev/docs/concepts2/retry

Shows a provider that fails and another that depends on it, causing a ProviderException, using riverpod_generator.

```dart
@riverpod  
int failed(MyProviderRef ref) {  
  throw Exception('This provider always fails');  
}  
  
@riverpod  
int myProvider(MyProviderRef ref) {  
  // This provider depends on a failed provider,  
  // and will therefore throw a ProviderException  
  return ref.watch(failedProvider);  
}  

```

--------------------------------

### Provider: Define and read with context.watch

Source: https://riverpod.dev/docs/from_provider/provider_vs_riverpod

Shows how to define a provider with Provider and read it using BuildContext.watch inside a StatelessWidget. This is the starting point for the comparison with Riverpod.

```dart
Provider<Model>(...);  

```

```dart
class Example extends StatelessWidget {  
  @override  
  Widget build(BuildContext context) {  
    Model model = context.watch<Model>();  
  
  }  
}  

```

--------------------------------

### Using cacheFor with FutureProvider.autoDispose (riverpod)

Source: https://riverpod.dev/docs/concepts2/auto_dispose

Shows how to use the cacheFor extension in a FutureProvider.autoDispose to keep the state alive for 5 minutes. The provider returns an HTTP GET request to example.com.

```dart
final provider = FutureProvider.autoDispose<Object>((ref) async {  
  /// Keeps the state alive for 5 minutes  
  ref.cacheFor(const Duration(minutes: 5));  
  
  return http.get(Uri.https('example.com'));  
});  

```

--------------------------------

### Generated provider watching another provider and widget

Source: https://riverpod.dev/docs/whats_new

Shows a generated provider that watches exampleProvider and a widget that reads anotherProvider on button press. This is the generated syntax equivalent to the manual example.

```dart
@riverpod  
int another(Ref ref) {  
  ref.keepAlive();  
  return ref.watch(exampleProvider);  
}  
  
class MyWidget extends ConsumerWidget {  
  @override  
  Widget build(BuildContext context, WidgetRef ref) {  
    return Button(  
      onPressed: () {  
        ref.read(anotherProvider);  
      },  
      child: Text('Click me'),  
    );  
  }  
}  

```

--------------------------------

### StateNotifier example class

Source: https://riverpod.dev/docs/migration/0.13.0_to_0.14.0

Defines a simple StateNotifier and its state model used throughout the migration guide.

```dart
class MyModel {}  
  
class MyStateNotifier extends StateNotifier<MyModel> {  
  MyStateNotifier(): super(MyModel());  
}  

```

--------------------------------

### JSON response from Random Joke API

Source: https://riverpod.dev/docs/tutorials/first_app

Example JSON object returned by the Random Joke generator API. It contains fields: type, setup, punchline, and id.

```json
{  
  "type": "general",  
  "setup": "Why did the scarecrow win an award?",  
  "punchline": "Because he was outstanding in his field.",  
  "id": 333  
}  

```

--------------------------------

### Flutter pubspec.yaml dependencies for Riverpod

Source: https://riverpod.dev/docs/introduction/getting_started

pubspec.yaml entries for Flutter projects. Choose the variant matching your setup: riverpod, hooks, or code generation. Place the selected block in your pubspec.yaml and run flutter pub get.

```yaml
name: my_app_name  
environment:  
  sdk: ^3.12.0  
  flutter: ">=3.44.0"  
  
dependencies:  
  flutter:  
    sdk: flutter  
  material_ui: ^1.0.0  
  flutter_riverpod: ^3.4.3  

```

```yaml
name: my_app_name  
environment:  
  sdk: ^3.12.0  
  flutter: ">=3.44.0"  
  
dependencies:  
  flutter:  
    sdk: flutter  
  material_ui: ^1.0.0  
  hooks_riverpod: ^3.4.3  
  flutter_hooks:  

```

```yaml
name: my_app_name  
environment:  
  sdk: ^3.12.0  
  flutter: ">=3.44.0"  
  
dependencies:  
  flutter:  
    sdk: flutter  
  material_ui: ^1.0.0  
  flutter_riverpod: ^3.4.3  
  riverpod_annotation: ^4.0.7  
  
dev_dependencies:  
  build_runner:  
  riverpod_generator: ^4.0.9  

```

```yaml
name: my_app_name  
environment:  
  sdk: ^3.12.0  
  flutter: ">=3.44.0"  
  
dependencies:  
  flutter:  
    sdk: flutter  
  material_ui: ^1.0.0  
  hooks_riverpod: ^3.4.3  
  flutter_hooks:  
  riverpod_annotation: ^4.0.7  
  
dev_dependencies:  
  build_runner:  
  riverpod_generator: ^4.0.9  

```

--------------------------------

### Hello world with Flutter Riverpod

Source: https://riverpod.dev/docs/introduction/getting_started

Flutter example using `package:flutter_riverpod` to display "Hello world" via a provider. Requires wrapping the app in a `ProviderScope` and extending `ConsumerWidget` to watch the provider with `ref.watch`.

```dart
import 'package:flutter_riverpod/flutter_riverpod.dart';  
import 'package:material_ui/material_ui.dart';  
  
// We create a "provider", which will store a value (here "Hello world").  
// By using a provider, this allows us to mock/override the value exposed.  
final helloWorldProvider = Provider((_) => 'Hello world');  
  
void main() {  
  runApp(  
    // For widgets to be able to read providers, we need to wrap the entire  
    // application in a "ProviderScope" widget.  
    // This is where the state of our providers will be stored.  
    ProviderScope(  
      child: MyApp(),  
    ),  
  );  
}  
  
// Extend ConsumerWidget instead of StatelessWidget, which is exposed by Riverpod  
class MyApp extends ConsumerWidget {  
  @override  
  Widget build(BuildContext context, WidgetRef ref) {  
    final String value = ref.watch(helloWorldProvider);  
  
    return MaterialApp(  
      home: Scaffold(  
        appBar: AppBar(title: const Text('Example')),  
        body: Center(  
          child: Text(value),  
        ),  
      ),  
    );  
  }  
}  

```

--------------------------------

### Scoping a mutation with generic return type

Source: https://riverpod.dev/docs/concepts2/mutations

Example of a mutation with a generic return type, where the response type depends on input parameters. The mutation is called with a type argument and a key, and the run callback uses a transaction to get a provider and perform a request.

```dart
final create = Mutation<ApiResponse>();  
final createTodo = create<CreatedResponse<Todo>>('create_todo');  
  
Future<void> executeCreateTodo(MutationTarget ref) async {  
  await createTodo.run(ref, (tsx) async {  
    final client = tsx.get(apiProvider);  
    final response = client.post('/todos', data: {'title': 'Eat a cookie'});  
    return CreatedResponse<Todo>.fromJson(response.data, Todo.fromJson);  
  });  
}  

```

--------------------------------

### Hello world with plain Riverpod (lib/main.dart)

Source: https://riverpod.dev/docs/introduction/getting_started

Console app using plain Riverpod to read a provider with ProviderContainer. Outputs 'Hello world'. Requires only the riverpod package.

```dart
import 'package:riverpod/riverpod.dart';  
  
// We create a "provider", which will store a value (here "Hello world").  
// By using a provider, this allows us to mock/override the value exposed.  
final helloWorldProvider = Provider((_) => 'Hello world');  
  
void main() {  
  // This object is where the state of our providers will be stored.  
  final container = ProviderContainer();  
  
  // Thanks to "container", we can read our provider.  
  final value = container.read(helloWorldProvider);  
  
  print(value); // Hello world  
}  

```

--------------------------------

### Initialize notifier with async build (standard)

Source: https://riverpod.dev/docs/migration/from_change_notifier

Shows how to initialize the notifier by performing an HTTP GET request inside build and returning the parsed list of todos. The provider is defined with AsyncNotifierProvider.autoDispose.

```dart
class MyNotifier extends AsyncNotifier<List<Todo>> {  
  @override  
  FutureOr<List<Todo>> build() async {  
    final json = await http.get('api/todos');  
    return [...json.map(Todo.fromJson)];  
  }  
}  
  
final myNotifierProvider =  
    AsyncNotifierProvider.autoDispose<MyNotifier, List<Todo>>(MyNotifier.new);  

```

--------------------------------

### FutureProvider.overrideWithValue (generated provider)

Source: https://riverpod.dev/docs/whats_new

Same as the manual example but using the generated provider from riverpod_generator.

```dart
@riverpod  
Future<int> myFutureProvider() async {  
  return 42;  
}  
  
void main() {  
  final container = ProviderContainer.test(  
    overrides: [  
      // Initializes the provider with a value.  
      // Changing the override will update the value.  
      myFutureProvider.overrideWithValue(AsyncValue.data(42)),  
    ],  
  );  
}  

```

--------------------------------

### Create a new Flutter project

Source: https://riverpod.dev/docs/tutorials/first_app

Run this command in your terminal to create a new Flutter project named 'first_app'.

```bash
flutter create first_app  
```

--------------------------------

### Hello world with riverpod_generator (lib/main.dart)

Source: https://riverpod.dev/docs/introduction/getting_started

Console app using riverpod_annotation to generate a provider. Requires riverpod_generator. Run with 'dart lib/main.dart' to print 'Hello world'.

```dart
import 'package:riverpod_annotation/riverpod_annotation.dart';  
  
part 'main.g.dart';  
  
// We create a "provider", which will store a value (here "Hello world").  
// By using a provider, this allows us to mock/override the value exposed.  
@riverpod  
String helloWorld(Ref ref) {  
  return 'Hello world';  
}  
  
void main() {  
  // This object is where the state of our providers will be stored.  
  final container = ProviderContainer();  
  
  // Thanks to "container", we can read our provider.  
  final value = container.read(helloWorldProvider);  
  
  print(value); // Hello world  
}  

```

--------------------------------

### Define a provider with riverpod_generator

Source: https://riverpod.dev/docs/how_to/testing

An eagerly initialized provider using the @riverpod annotation. This is the provider to be mocked in the examples.

```dart
// An eagerly initialized provider.  
@riverpod  
Future<String> example(Ref ref) async => 'Hello world';  

```

--------------------------------

### Manually pause and resume a ref.listen subscription

Source: https://riverpod.dev/docs/whats_new

Creates a subscription to a provider using `ref.listen` and demonstrates calling `pause()` and `resume()` on the returned subscription object to control when the listener receives updates.

```dart
final subscription = ref.listen(  
  todoListProvider,  
  (previous, next) {  
    // Do something with the new value  
  },  
);  
  
subscription.pause();  
subscription.resume();  

```

--------------------------------

### Hello world with Flutter hooks and Riverpod (lib/main.dart)

Source: https://riverpod.dev/docs/introduction/getting_started

Flutter app using hooks_riverpod to display 'Hello world' with a counter. Requires flutter_hooks, Material UI, and riverpod_generator dependencies. Run with 'flutter run'.

```dart
import 'package:flutter_hooks/flutter_hooks.dart';  
import 'package:hooks_riverpod/hooks_riverpod.dart';  
import 'package:material_ui/material_ui.dart';  
import 'package:riverpod_annotation/riverpod_annotation.dart';  
  
part 'main.g.dart';  
  
// We create a "provider", which will store a value (here "Hello world").  
// By using a provider, this allows us to mock/override the value exposed.  
@riverpod  
String helloWorld(Ref ref) {  
  return 'Hello world';  
}  
  
void main() {  
  runApp(  
    // For widgets to be able to read providers, we need to wrap the entire  
    // application in a "ProviderScope" widget.  
    // This is where the state of our providers will be stored.  
    ProviderScope(  
      child: MyApp(),  
    ),  
  );  
}  
  
// Extend HookConsumerWidget instead of HookWidget, which is exposed by Riverpod  
class MyApp extends HookConsumerWidget {  
  @override  
  Widget build(BuildContext context, WidgetRef ref) {  
    // We can use hooks inside HookConsumerWidget  
    final counter = useState(0);  
  
    final String value = ref.watch(helloWorldProvider);  
  
    return MaterialApp(  
      home: Scaffold(  
        appBar: AppBar(title: const Text('Example')),  
        body: Center(  
          child: Text('$value ${counter.value}'),  
        ),  
      ),  
    );  
  }  
}  

```

--------------------------------

### Using ConsumerStatefulWidget and ConsumerState

Source: https://riverpod.dev/docs/concepts2/consumers

Subclass ConsumerStatefulWidget and ConsumerState to get a ref property. This is the stateful variant of ConsumerWidget.

```dart
// We subclass ConsumerStatefulWidget instead of StatefulWidget  
class MyWidget extends ConsumerStatefulWidget {  
  @override  
  ConsumerState<MyWidget> createState() => _MyWidgetState();  
}  
// We subclass ConsumerState instead of State  
class _MyWidgetState extends ConsumerState<MyWidget> {  
  // A "this.ref" property is available  
  @override  
  Widget build(BuildContext context) {  
    // We can use that "ref" to listen to providers  
    final value = ref.watch(myProvider);  
    return Text(value.toString());  
  }  
}  

```

--------------------------------

### Migrate FutureProvider to AsyncNotifier with state and listenSelf

Source: https://riverpod.dev/docs/3.0_migration

Shows the manual migration from a FutureProvider using ref.state, ref.listenSelf, and ref.future to an AsyncNotifier class using state, listenSelf, and future. Note the state update now uses AsyncData and state.valueOrNull.

```dart
// Before:  
final valueProvider = FutureProvider<int>((ref) async {  
  ref.listen(anotherProvider, (previous, next) {  
    ref.state++;  
  });  
    
  ref.listenSelf((previous, next) {  
    print('Log: $previous -> $next');  
  });  
    
  ref.future.then((value) {  
    print('Future: $value');  
  });  
  
  return 0;  
});  
  
// After  
class Value extends AsyncNotifier<int> {  
  @override  
  Future<int> build() async {  
    ref.listen(anotherProvider, (previous, next) {  
      state = AsyncData((state.valueOrNull ?? 0) + 1);  
    });  
    
    listenSelf((previous, next) {  
      print('Log: $previous -> $next');  
    });  
    
    future.then((value) {  
      print('Future: $value');  
    });  
    
    return 0;  
  }  
}  
final valueProvider = AsyncNotifierProvider<Value, int>(Value.new);  

```

--------------------------------

### Switching over mutation states

Source: https://riverpod.dev/docs/concepts2/mutations

Example of a switch statement over the different mutation states: MutationIdle, MutationPending, MutationError, and MutationSuccess.

```dart
switch (addTodoState) {  
  case MutationIdle():  
  // Show a button to add a todo  
  case MutationPending():  
  // Show a loading indicator  
  case MutationError():  
  // Show an error message  
  case MutationSuccess():  
  // Show the created todo  
}  

```

--------------------------------

### Modifiable provider example (public setter)

Source: https://riverpod.dev/docs/concepts2/providers

Illustrates a modifiable provider: anything can modify the state, similar to a public setter.

```dart
// Anything can modify "state"  
var state = 0;  

```

--------------------------------

### Initialize notifier with async build (codegen)

Source: https://riverpod.dev/docs/migration/from_change_notifier

Shows how to initialize the notifier with an async build method that fetches data from an API. The class is annotated with @riverpod and extends _$MyNotifier.

```dart
@riverpod  
class MyNotifier extends _$MyNotifier {  
  @override  
  FutureOr<List<Todo>> build() async {  
    final json = await http.get('api/todos');  
    return [...json.map(Todo.fromJson)];  
  }  
}  

```

--------------------------------

### Create the home screen with ProviderScope and navigation

Source: https://riverpod.dev/docs/how_to/cancel

Defines the home screen with a ProviderScope at the root, a MaterialApp with a route to '/detail-page', and an ActivityView that uses a FloatingActionButton to navigate to the detail page.

```dart
void main() => runApp(const ProviderScope(child: MyApp()));  
  
class MyApp extends StatelessWidget {  
  const MyApp({super.key});  
  
  @override  
  Widget build(BuildContext context) {  
    return MaterialApp(  
      routes: {  
        '/detail-page': (_) => const DetailPageView(),  
      },  
      home: const ActivityView(),  
    );  
  }  
}  
  
class ActivityView extends ConsumerWidget {  
  const ActivityView({super.key});  
  
  @override  
  Widget build(BuildContext context, WidgetRef ref) {  
    return Scaffold(  
      appBar: AppBar(title: const Text('Home screen')),  
      body: const Center(  
        child: Text('Click the button to open the detail page'),  
      ),  
      floatingActionButton: FloatingActionButton(  
        onPressed: () => Navigator.of(context).pushNamed('/detail-page'),  
        child: const Icon(Icons.add),  
      ),  
    );  
  }  
}  

```

--------------------------------

### Notifier with listenSelf (riverpod)

Source: https://riverpod.dev/docs/migration/from_state_notifier

Replacement for the old StateNotifier example using Notifier and listenSelf. This is the riverpod syntax without code generation.

```dart
class MyNotifier extends Notifier<int> {  
  @override  
  int build() {  
    listenSelf((_, next) => debugPrint('$next'));  
    return 0;  
  }  
  
  void add() => state++;  
}  
  
final myNotifierProvider = NotifierProvider<MyNotifier, int>(MyNotifier.new);  
```

--------------------------------

### New Notifier syntax (codegen)

Source: https://riverpod.dev/docs/migration/from_state_notifier

The same counter example using the riverpod_generator codegen approach. The class extends _$CounterNotifier and is annotated with @riverpod.

```dart
@riverpod  
class CounterNotifier extends _$CounterNotifier {  
  @override  
  int build() => 0;  
  
  void increment() => state++;  
  void decrement() => state--;  
}  

```

--------------------------------

### Enable riverpod_lint in analysis_options.yaml

Source: https://riverpod.dev/docs/introduction/getting_started

Add the `riverpod_lint` package as a plugin in your `analysis_options.yaml` file, next to your `pubspec.yaml`, to enable lint rules and custom refactorings. Replace `<latest version from https://pub.dev/packages/riverpod_lint>` with the current version from the provided URL.

```yaml
plugins:  
  riverpod_lint: <latest version from https://pub.dev/packages/riverpod_lint>  

```

--------------------------------

### Notifier with @riverpod annotation and build method

Source: https://riverpod.dev/docs/concepts2/providers

Example of a notifier class annotated with @riverpod, extending _$MyNotifier, and overriding the build method.

```dart
@riverpod
class MyNotifier extends _$MyNotifier {
  @override
  Result build() {
    <your logic here>
  }
  <your methods here>
}

```

--------------------------------

### Eagerly initialize providers by watching them in a Consumer under ProviderScope

Source: https://riverpod.dev/docs/how_to/eager_initialization

Place a ConsumerWidget that watches the provider and returns its child. This keeps the provider alive and prevents disposal. The child is passed as a parameter to avoid rebuilding the entire app when the provider changes.

```dart
void main() {  
  runApp(ProviderScope(child: MyApp()));  
}  
  
class MyApp extends StatelessWidget {  
  @override  
  Widget build(BuildContext context) {  
    return const _EagerInitialization(  
      // TODO: Render your app here  
      child: MaterialApp(),  
    );  
  }  
}  
  
class _EagerInitialization extends ConsumerWidget {  
  const _EagerInitialization({required this.child});  
  final Widget child;  
  
  @override  
  Widget build(BuildContext context, WidgetRef ref) {  
    // Eagerly initialize providers by watching them.  
    // By using "watch", the provider will stay alive and not be disposed.  
    ref.watch(myProvider);  
    return child;  
  }  
}  

```

--------------------------------

### Obtain a ProviderContainer in widget tests

Source: https://riverpod.dev/docs/how_to/testing

Shows how to get a ProviderContainer using tester.container() inside a widget test, enabling interaction with providers.

```dart
final container = tester.container();  

```

--------------------------------

### Riverpod 2.0 auto-dispose async gap example (generator providers)

Source: https://riverpod.dev/docs/whats_new

Shows the same problematic behavior using riverpod_generator syntax with @riverpod annotations.

```dart
@riverpod  
Stream<int> autoDispose(Ref ref) {  
  ref.onDispose(() => print('disposed'));  
  ref.onCancel(() => print('paused'));  
  ref.onResume(() => print('resumed'));  
  // A stream that emits a value every second  
  return Stream.periodic(Duration(seconds: 1), (i) => i);  
}  
  
@riverpod  
Future<int> asynchronousExample(Ref ref) async {  
  print('Before async gap');  
  // An async gap inside a provider ; typically an API call.  
  // This will dispose the "autoDispose" provider  
  // before the async operation is completed  
  await null;  
    
  print('after async gap');  
  // We listen to our auto-dispose provider  
  // after the async operation  
  return ref.watch(autoDisposeProvider.future);  
}  
  
void main() {  
  final container = ProviderContainer();  
  // This will print 'disposed' every second,  
  // and will constantly print 0  
  container.listen(asynchronousExampleProvider, (_, value) {  
    if (value is AsyncData) print('${value.value}\n----');  
  });  
}  

```

--------------------------------

### Using cacheFor with @riverpod generator (riverpod_generator)

Source: https://riverpod.dev/docs/concepts2/auto_dispose

Shows how to use the cacheFor extension in a generated provider using @riverpod. The provider keeps state alive for 5 minutes and returns an HTTP GET request to example.com.

```dart
@riverpod  
Future<Object> example(Ref ref) async {  
  /// Keeps the state alive for 5 minutes  
  ref.cacheFor(const Duration(minutes: 5));  
  
  return http.get(Uri.https('example.com'));  
}  

```

--------------------------------

### Multiple providers of the same type with package:provider

Source: https://riverpod.dev/docs/concepts2/providers

Shows how to create multiple providers of the same type using the classic Provider from package:provider.

```dart
final cityProvider = Provider((ref) => 'London');  
final countryProvider = Provider((ref) => 'England');  

```

--------------------------------

### Notifier with listenSelf (riverpod_generator)

Source: https://riverpod.dev/docs/migration/from_state_notifier

Replacement for the old StateNotifier example using Notifier and listenSelf, using the @riverpod annotation and generated base class.

```dart
@riverpod  
class MyNotifier extends _$MyNotifier {  
  @override  
  int build() {  
    listenSelf((_, next) => debugPrint('$next'));  
    return 0;  
  }  
  
  void add() => state++;  
}  
```

--------------------------------

### Mock a provider in unit and widget tests

Source: https://riverpod.dev/docs/how_to/testing

Shows how to mock a provider using the overrides parameter. In unit tests, use ProviderContainer.test; in widget tests, use ProviderScope. The example overrides exampleProvider to return 'Hello from tests'.

```dart
// In unit tests, by reusing our previous "createContainer" utility.  
final container = ProviderContainer.test(  
  // We can specify a list of providers to mock:  
  overrides: [  
    // In this case, we are mocking "exampleProvider".  
    exampleProvider.overrideWith((ref) {  
      // This function is the typical initialization function of a provider.  
      // This is where you normally call "ref.watch" and return the initial state.  
  
      // Let's replace the default "Hello world" with a custom value.  
      // Then, interacting with `exampleProvider` will return this value.  
      return 'Hello from tests';  
    }),  
  ],  
);  
  
// We can also do the same thing in widget tests using ProviderScope:  
await tester.pumpWidget(  
  ProviderScope(  
    // ProviderScopes have the exact same "overrides" parameter  
    overrides: [  
      // Same as before  
      exampleProvider.overrideWith((ref) => 'Hello from tests'),  
    ],  
    child: const YourWidgetYouWantToTest(),  
  ),  
);  

```

--------------------------------

### Unmodifiable provider example (private setter)

Source: https://riverpod.dev/docs/concepts2/providers

Illustrates an unmodifiable provider: the state is internally modifiable but cannot be modified externally, similar to a private setter.

```dart
// _state is internally modifiable  
// but cannot be modified externally  
var _state = 0;  
int get state => _state;  

```

--------------------------------

### Generated provider with onCancel/onResume callbacks

Source: https://riverpod.dev/docs/whats_new

Defines a provider using the @riverpod annotation with keepAlive and onCancel/onResume callbacks. This is the generated syntax equivalent to the manual example.

```dart
@riverpod  
int example(Ref ref) {  
  ref.keepAlive();  
  ref.onCancel(() => print('paused'));  
  ref.onResume(() => print('resumed'));  
  return 0;  
}  

```

--------------------------------

### Use provider with Consumer widget

Source: https://riverpod.dev/docs/concepts2/providers

Shows how to obtain a provider value inside a widget using a Consumer and ref.watch. The helloWorldProvider is assumed to be defined elsewhere.

```dart
class Example extends StatelessWidget {  
  @override  
  Widget build(BuildContext context) {  
    return Consumer(  
      builder: (context, ref, _) {  
        // Obtain the value of the provider  
        final helloWorld = ref.watch(helloWorldProvider);  
  
        // Use the value in the UI  
        return Text(helloWorld);  
      },  
    );  
  }  
}  

```

--------------------------------

### Set up offline persistence with JsonSqFliteStorage and TodosNotifier

Source: https://riverpod.dev/docs/whats_new

Defines a storage provider that opens a SQLite database, a Freezed Todo model, and a TodosNotifier that persists its state. The persist call reads the database on first build and writes changes automatically. The cache duration defaults to 2 days, and the server state takes precedence after a network fetch.

```dart
@riverpod  
Future<JsonSqFliteStorage> storage(Ref ref) async {  
  // Initialize SQFlite. We should share the Storage instance between providers.  
  return JsonSqFliteStorage.open(  
    join(await getDatabasesPath(), 'riverpod.db'),  
  );  
}  
  
/// A serializable Todo class. We're using Freezed for simple serialization.  
@freezed  
abstract class Todo with _$Todo {  
  const factory Todo({  
    required int id,  
    required String description,  
    required bool completed,  
  }) = _Todo;  
  
  factory Todo.fromJson(Map<String, dynamic> json) => _$TodoFromJson(json);  
}  
  
@riverpod  
@JsonPersist()  
class TodosNotifier extends _$TodosNotifier {  
  @override  
  FutureOr<List<Todo>> build() async {  
    // We call persist at the start of our 'build' method.  
    // This will:  
    // - Read the DB and update the state with the persisted value the first  
    //   time this method executes.  
    // - Listen to changes on this provider and write those changes to the DB.  
    persist(  
      // We pass our JsonSqFliteStorage instance. No need to "await" the Future.  
      // Riverpod will take care of that.  
      ref.watch(storageProvider.future),  
      // By default, state is cached offline only for 2 days.  
      // We can optionally uncomment the following line to change cache duration.  
      // options: const StorageOptions(cacheTime: StorageCacheTime.unsafe_forever),  
    );  
  
    // We asynchronously fetch todos from the server.  
    // During the await, the persisted todo list will be available.  
    // After the network request completes, the server state will take precedence  
    // over the persisted state.  
    final todos = await fetchTodos();  
    return todos;  
  }  
  
  Future<void> add(Todo todo) async {  
    // When modifying the state, no need for any extra logic to persist the change.  
    // Riverpod will automatically cache the new state and write it to the DB.  
    state = AsyncData([...await future, todo]);  
  }  
}  

```
Tokens:
Raw