Provider

What Is a Provider?

In Riverpod, a provider is a piece of logic that holds a value and can be listened to by widgets. Providers are the fundamental building blocks of Riverpod. They are:

Global — they can be accessed from anywhere in your app
Type-safe — they hold a specific type of value
Reactive — widgets can listen to them and rebuild when the value changes
Composable — providers can depend on other providers

✅ The Big Idea

Think of a provider as a container for state that lives outside your widget tree. You define providers globally, and then your widgets can watch them to get the current value and rebuild when it changes.

How Providers Work

A provider is defined using a simple function that returns a value. Here's the basic structure:

lib/providers.dart – Defining a Provider


        
         final
        
        myProvider = Provider<String>((ref) {
        
         // This function is called once when the provider is first read
        
        
         return
        
        
         'Hello, World!'
        
        ;
  });

1. `final myProvider`

The provider is declared as a top-level final variable. This makes it globally accessible.

2. `Provider<String>`

The type parameter tells Riverpod what type of value this provider holds.

3. `(ref) => ...`

The creation function. It receives a ref object that can be used to read other providers.

4. `return 'Hello, World!';`

The value that the provider exposes. This can be any Dart object.

Reading Providers

There are three main ways to interact with providers in your widgets:

👀

ref.watch()

Listens to a provider and rebuilds the widget when the provider's value changes.

Use in build() method

Source Code


          
           final
          
          value = ref.watch(myProvider);

📖

ref.read()

Reads a provider once without listening for changes. The widget does not rebuild.

Use in callbacks, event handlers

Source Code


          
           final
          
          value = ref.read(myProvider);

🔔

ref.listen()

Runs a callback when the provider's value changes. The widget does not rebuild.

Use for side effects (navigation, logging)

Source Code


          ref.listen<String>(myProvider, (prev, next) {
          

          print('Value changed to: $next');
          

          });

🔗

ref.read().notifier

Gets the notifier of a provider (for StateProvider, StateNotifierProvider) to update state.

Use to update state from callbacks

Source Code


          ref.read(myProvider.notifier).state = newValue;

Types of Providers

Riverpod offers several provider types, each designed for a specific use case:

📦

The simplest provider. Holds a value that never changes after initialization. Good for dependencies, configuration, and services.

Source Code


          
           final
          
          apiProvider = Provider<ApiService>((ref) => ApiService());

🔄

StateProvider

Holds a mutable piece of state. Use for simple state like counters, booleans, or strings.

Source Code


          
           final
          
          counterProvider = StateProvider<int>((ref) => 0);

⚡

FutureProvider

Holds a Future . Perfect for asynchronous data fetching like API calls. Handles loading, data, and error states.

Source Code


          
           final
          
          userProvider = FutureProvider<User>((ref) async {
          

          
           return
          
          await fetchUser();
          

          });

🌊

StreamProvider

Holds a Stream . Ideal for real-time data like Firebase Firestore streams.

Source Code


          
           final
          
          messagesProvider = StreamProvider<Message>((ref) {
          

          
           return
          
          chatService.messagesStream;
          

          });

🎯

StateNotifierProvider

The most powerful provider. Holds a StateNotifier that manages complex state with methods. Best for forms, lists, and complex business logic.

Source Code


          
           final
          
          todoProvider = StateNotifierProvider<TodoNotifier, TodoState>((ref) {
          

          
           return
          
          TodoNotifier();
          

          });

Complete Example: Dependency Injection

A common use case for the basic Provider is dependency injection . You can use providers to make services, repositories, or configuration objects available throughout your app.

lib/providers.dart – Dependency Injection


        
         import
        
        
         'package:flutter_riverpod/flutter_riverpod.dart'
        
        ;
        
         // A simple service class
        
        
         class
        
        
         ApiService
        
        {
        
         Future
        
        <String>
        
         fetchData
        
        () async {
        
         // Simulate network request
        
        await Future.delayed(Duration(seconds: 1));
        
         return
        
        
         'Fetched data from API'
        
        ;
    }
  }
        
         // 1. Define a provider that holds the ApiService instance
        
        
         final
        
        apiServiceProvider = Provider<ApiService>((ref) {
        
         return
        
        ApiService();
        
         // The service is created once and reused
        
        });
        
         // 2. Another provider that depends on the first one
        
        
         final
        
        greetingProvider = Provider<String>((ref) {
        
         // Watch the apiServiceProvider to get the service
        
        
         final
        
        api = ref.watch(apiServiceProvider);
        
         return
        
        
         'Using API service: ${api.runtimeType}'
        
        ;
  });

lib/main.dart – Using Providers in Widgets


        
         import
        
        
         'package:flutter/material.dart'
        
        ;
        
         import
        
        
         'package:flutter_riverpod/flutter_riverpod.dart'
        
        ;
        
         import
        
        
         'providers.dart'
        
        ;
        
         void
        
        
         main
        
        () {
    runApp(
      ProviderScope(
        child: MyApp(),
      ),
    );
  }
        
         class
        
        
         MyApp
        
        
         extends
        
        StatelessWidget {
    @override
    Widget
        
         build
        
        (BuildContext context) {
        
         return
        
        MaterialApp(
        home: HomeScreen(),
      );
    }
  }
        
         class
        
        
         HomeScreen
        
        
         extends
        
        ConsumerWidget {
    @override
    Widget
        
         build
        
        (BuildContext context, WidgetRef ref) {
        
         // 3. Watch the greeting provider to get the value
        
        
         final
        
        greeting = ref.watch(greetingProvider);
        
         return
        
        Scaffold(
        appBar: AppBar(title: Text(
        
         'Dependency Injection'
        
        )),
        body: Center(
          child: Text(greeting),
        ),
      );
    }
  }

Step-by-Step Explanation

1.

Define ApiService – A simple Dart class that simulates an API service. In a real app, this might make HTTP requests or interact with a database.

2.

apiServiceProvider – A


          Provider

that creates and holds an


          ApiService

instance. This ensures the service is created once and reused throughout the app.

3.

greetingProvider – This provider depends on


          apiServiceProvider

. It uses


          ref.watch()

to get the service and creates a greeting string.

4.

ProviderScope – The required root widget for Riverpod. It stores all provider states.

5.

ConsumerWidget – Instead of


          StatelessWidget

, we use


          ConsumerWidget

to get access to

ref

. We watch


          greetingProvider

and display its value.

Provider Dependencies (Composition)

One of the most powerful features of Riverpod is that providers can depend on other providers. This is called provider composition .

🔗 How Provider Composition Works

When a provider depends on another provider, it uses ref.watch() to read the value. If the depended-upon provider changes, the dependent provider also updates. This creates a reactive dependency graph .

lib/providers.dart – Provider Composition


        
         // Provider 1: Holds a counter value
        
        
         final
        
        counterProvider = StateProvider<int>((ref) => 0);
        
         // Provider 2: Depends on counterProvider
        
        
         final
        
        doubledCounterProvider = Provider<int>((ref) {
        
         final
        
        count = ref.watch(counterProvider);
        
         // 👈 Watch the dependency
        
        
         return
        
        count * 2;
        
         // 👈 Compute derived state
        
        });
        
         // Provider 3: Depends on doubledCounterProvider
        
        
         final
        
        messageProvider = Provider<String>((ref) {
        
         final
        
        doubled = ref.watch(doubledCounterProvider);
        
         return
        
        
         'The doubled value is: $doubled'
        
        ;
  });

✅ Why This Is Powerful

Reactive updates – When counterProvider changes, both doubledCounterProvider and messageProvider update automatically.
Clean separation – Each provider has a single responsibility.
Testability – Each provider can be tested in isolation.
Performance – Only the widgets that watch specific providers rebuild.

Common Mistakes

❌ Mistake 1: Using ref.watch() inside event handlers

ref.watch() is only valid inside the build() method of a ConsumerWidget or inside a provider's creation function. Using it in callbacks will throw an error.

✅ Correct: Use ref.read() in event handlers

For buttons, taps, and other callbacks, use ref.read() to read the current value without listening for changes.

❌ Mistake 2: Creating providers inside widgets

Providers should be declared as top-level final variables , not inside widgets. Declaring them inside widgets breaks the global accessibility and can lead to unexpected behavior.

✅ Correct: Declare providers at top level

final myProvider = Provider<String>((ref) => 'value'); should be at the top of your file, outside any class.

❌ Mistake 3: Not wrapping the app with ProviderScope

Without ProviderScope , Riverpod cannot store provider states. This will cause runtime errors.

✅ Correct: Always use ProviderScope at the root

runApp(ProviderScope(child: MyApp())); is the standard way to initialize Riverpod.

Provider

✅ The Big Idea

1. final myProvider

2. Provider<String>

3. (ref) => ...

4. return 'Hello, World!';

ref.watch()

ref.read()

ref.listen()

ref.read().notifier

Provider

StateProvider

FutureProvider

StreamProvider

StateNotifierProvider

🔗 How Provider Composition Works

✅ Why This Is Powerful

🎯 Key Takeaway

1. `final myProvider`

2. `Provider<String>`

3. `(ref) => ...`

4. `return 'Hello, World!';`