Riverpod overview

Why Riverpod?

Provider is simple, but it depends on the widget tree: reading a provider that is not above you fails at run time, and two providers of the same type are awkward. Riverpod, created by the same author (Remi Rousselet), fixes these: providers are declared once as top-level definitions, missing providers are compile errors rather than run-time crashes, and state can be read and tested without a BuildContext.

The core pieces

Providers in Riverpod are lazy and cached: a provider runs only when something first reads it, and its value is kept while something is listening. Providers can also read other providers with ref.watch inside their own definition, so a cart total provider can depend on the cart provider and update whenever the cart changes.

A counter with a Notifier

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

class CartCount extends Notifier<int> {
  @override
  int build() => 0;                      // initial state

  void add() => state = state + 1;       // assigning state notifies listeners
}

final cartCountProvider = NotifierProvider<CartCount, int>(CartCount.new);

void main() => runApp(const ProviderScope(child: MaterialApp(home: CartScreen())));

class CartScreen extends ConsumerWidget {
  const CartScreen({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(cartCountProvider);
    return Scaffold(
      body: Center(child: Text('Items: $count')),
      floatingActionButton: FloatingActionButton(
        onPressed: () => ref.read(cartCountProvider.notifier).add(),
        child: const Icon(Icons.add),
      ),
    );
  }
}

Async data with FutureProvider

final weatherProvider = FutureProvider<String>((ref) async {
  await Future.delayed(const Duration(seconds: 1));      // pretend API call
  return 'Pune: 31°C';
});

class WeatherText extends ConsumerWidget {
  const WeatherText({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final weather = ref.watch(weatherProvider);
    return weather.when(
      data: (w) => Text(w),
      loading: () => const CircularProgressIndicator(),
      error: (e, st) => Text('Could not load: $e'),
    );
  }
}

Code generation (optional)

Riverpod also offers an optional code-generation style with @riverpod annotations and the riverpod_generator package, which writes provider declarations for you. Many teams use it; it is not required to start. Riverpod 3.0 (released in 2025) changed and simplified several APIs, and older tutorials may use outdated names such as StateNotifierProvider; follow riverpod.dev for current syntax.

Common mistakes

• Forgetting ProviderScope at the root: an error on the first read.
• Using ref.watch inside callbacks: use ref.read there.
• Mutating state in place (state.add(item)) in a Notifier: listeners are not notified. Assign a new value (state = [...state, item]).
• Copying old Riverpod 1.x/2.x tutorials without checking the current API.